From 153d37694a4938b2f9e6c4f7015a43913ce84c8a Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Tue, 17 Apr 2018 16:45:49 -0700 Subject: [PATCH 01/27] Separate identifiers into its own section. Clean up variables. --- docs/painless/painless-identifiers.asciidoc | 29 ++++ docs/painless/painless-keywords.asciidoc | 4 +- docs/painless/painless-lang-spec.asciidoc | 2 + docs/painless/painless-literals.asciidoc | 22 +-- docs/painless/painless-operators.asciidoc | 1 + docs/painless/painless-variables.asciidoc | 170 +++++++++++--------- 6 files changed, 136 insertions(+), 92 deletions(-) create mode 100644 docs/painless/painless-identifiers.asciidoc diff --git a/docs/painless/painless-identifiers.asciidoc b/docs/painless/painless-identifiers.asciidoc new file mode 100644 index 0000000000000..4b61b4f3d62ee --- /dev/null +++ b/docs/painless/painless-identifiers.asciidoc @@ -0,0 +1,29 @@ +[[painless-identifiers]] +=== Identifiers + +Specify identifiers to <>, <>, and +<> variables, <>, and +<>. <> and +<> cannot be used as identifiers. + +*Grammar* +[source,ANTLR4] +---- +ID: [_a-zA-Z] [_a-zA-Z-0-9]*; +---- + +*Examples* + +Variations of identifiers. + +[source,Painless] +---- +a +Z +id +list +list0 +MAP25 +_map25 +Map_25 +---- diff --git a/docs/painless/painless-keywords.asciidoc b/docs/painless/painless-keywords.asciidoc index 99b5b4060d24e..cb3bafbd20f13 100644 --- a/docs/painless/painless-keywords.asciidoc +++ b/docs/painless/painless-keywords.asciidoc @@ -2,8 +2,8 @@ === Keywords The keywords in the table below are reserved for built-in language -features. These keywords cannot be used as <> or -<>. +features. These keywords cannot be used as +<> or <>. [cols="^1,^1,^1,^1,^1"] |==== diff --git a/docs/painless/painless-lang-spec.asciidoc b/docs/painless/painless-lang-spec.asciidoc index b324ad301141c..ba6595000ae2f 100644 --- a/docs/painless/painless-lang-spec.asciidoc +++ b/docs/painless/painless-lang-spec.asciidoc @@ -23,6 +23,8 @@ include::painless-keywords.asciidoc[] include::painless-literals.asciidoc[] +include::painless-identifiers.asciidoc[] + include::painless-variables.asciidoc[] include::painless-types.asciidoc[] diff --git a/docs/painless/painless-literals.asciidoc b/docs/painless/painless-literals.asciidoc index 3f91c9299c0ad..191f3adb0c923 100644 --- a/docs/painless/painless-literals.asciidoc +++ b/docs/painless/painless-literals.asciidoc @@ -28,12 +28,12 @@ Integer literals. [source,Painless] ---- -0 <1> -0D <2> -1234L <3> --90f <4> --022 <5> -0xF2A <6> +<1> 0 +<2> 0D +<3> 1234L +<4> -90f +<5> -022 +<6> 0xF2A ---- <1> `int 0` @@ -65,11 +65,11 @@ Floating point literals. [source,Painless] ---- -0.0 <1> -1E6 <2> -0.977777 <3> --126.34 <4> -89.9F <5> +<1> 0.0 +<2> 1E6 +<3> 0.977777 +<4> -126.34 +<5> 89.9F ---- <1> `double 0.0` diff --git a/docs/painless/painless-operators.asciidoc b/docs/painless/painless-operators.asciidoc index 11ee97def66ba..915d811fa441b 100644 --- a/docs/painless/painless-operators.asciidoc +++ b/docs/painless/painless-operators.asciidoc @@ -704,6 +704,7 @@ e = ~d; // sets e the negation of d The cast operator can be used to explicitly convert one type to another. See casting [MARK] for more information. +[[constructor-call]] ==== Constructor Call A constructor call is a special type of method call [MARK] used to allocate a reference type instance using the new operator. The format is the new operator followed by a type, an opening parenthesis, arguments if any, and a closing parenthesis. Arguments are a series of zero-to-many expressions delimited by commas. Auto-boxing and auto-unboxing will be applied automatically for arguments passed into a constructor call. See boxing and unboxing [MARK] for more information on this topic. Constructor argument types can always be resolved at run-time; if appropriate type conversions (casting) cannot be applied an error will occur. Once a reference type instance has been allocated, its members may be used as part of other expressions. diff --git a/docs/painless/painless-variables.asciidoc b/docs/painless/painless-variables.asciidoc index 08725b328a3c2..b63558f9a25ec 100644 --- a/docs/painless/painless-variables.asciidoc +++ b/docs/painless/painless-variables.asciidoc @@ -1,122 +1,134 @@ [[painless-variables]] === Variables -Variables in Painless must be declared and can be -statically or <>. - -[[identifiers]] -==== Identifiers - -Specify variable identifiers using the following grammar. Variable identifiers -must start with a letter or underscore. You cannot use -<> or <> as identifiers. - -*Grammar:* -[source,ANTLR4] ----- -ID: [_a-zA-Z] [_a-zA-Z-0-9]*; ----- - -*Examples:* -[source,Java] ----- -a -Z -id -list -list0 -MAP25 -_map25 ----- +<> variables to <> values for +<> in expressions. Specify variables as a +<>, <>, or +<> type. [[declaration]] ==== Declaration -Variables must be declared before you use them. The format is `type-name -identifier-name`. To declare multiple variables of the same type, specify a -comma-separated list of identifier names. You can immediately assign a value to -a variable when you declare it. +Declare variables before use with the format of <> +<>. Specify a comma-separated list of +<> following the <> +to declare multiple variables in a single statement. Use +<> combined with a declaration statement to immediately +assign a value to a variable. Variables not immediately assigned a value will +have a default value assigned implicitly based on the <>. -*Grammar:* +*Grammar* [source,ANTLR4] ---- +declaration : type ID assignment? (',' ID assignment?)*; type: ID ('[' ']')*; -declaration : type ID (',' ID)*; +assignment: '=' expression; ---- -*Examples:* -[source,Java] +*Examples* + +Different variations of variable declaration. + +[source,Painless] ---- -int x; // Declare a variable with type int and id x -List y; // Declare a variable with type List and id y -int x, y, z; // Declare variables with type int and ids x, y, and z -def[] d; // Declare the variable d with type def[] -int i = 10; // Declare the int variable i and set it to the int literal 10 +<1> int x; +<2> List y; +<3> int x, y, z; +<4> def[] d; +<5> int i = 10; ---- -[[variable-assignment]] -==== Assignment +<1> declare a variable of type `int` and identifier `x` +<2> declare a variable of type `List` and identifier `y` +<3> declare three variables of type `int` and identifiers `x`, `y`, `z` +<4> declare a variable of type `def[]` and identifier `d` +<5> declare a variable of type `int` and identifier `i`; + assign the integer literal `10` to `i` -Use the equals operator (`=`) to assign a value to a variable. The format is -`identifier-name = value`. Any value expression can be assigned to any variable -as long as the types match or the expression's type can be implicitly cast to -the variable's type. An error occurs if the types do not match. +[[assignment]] +==== Assignment -*Grammar:* +Use the `equals` operator (`=`) to assign a value to a variable. Any expression +that produces a value can be assigned to any variable as long as the +<> are the same or the resultant +<> can be implicitly <> to +the variable <>. Otherwise, an error will occur. + +Assignment of <> will cause the value to be +copied. Assignment of <> will cause the +value to be referred to with the exception of the <> +which is copied. Assignment of <> will +cause the value to be copied or referred to based on what the +<> represents. All types of assignment follow +the standard Java memory model. + +*Grammar* [source,ANTLR4] ---- assignment: ID '=' expression ---- +*Examples* -*Examples:* +Variable assignment with an <>. -Assigning a literal of the appropriate type directly to a declared variable. - -[source,Java] +[source,Painless] ---- -int i;   // Declare an int i -i = 10;  // Set the int i to the int literal 10 +<1> int i; +<2> i = 10; ---- -Immediately assigning a value when declaring a variable. +<1> declare `int i` +<2> assign a copy of `10` to `i` + +<> combined with immediate variable assignment. -[source,Java] +[source,Painless] ---- -int i = 10; // Declare the int variable i and set it the int literal 1 -double j = 2.0; // Declare the double variable j and set it to the double - // literal 2.0 +<1> int i = 10; +<2> double j = 2.0; ---- -Assigning a variable of one primitive type to another variable of the same -type. +<1> declare `int i`; assign a copy of `10` to `i` +<2> declare `double j`; assign a copy of `2.0` to `j` -[source,Java] +Assignment of one variable to another using +<>. + +[source,Painless] ---- -int i = 10; // Declare the int variable i and set it to the int literal 10 -int j = i;  // Declare the int variable j and set it to the int variable i +<1> int i = 10; +<2> int j = i; ---- -Assigning a reference type to a new heap allocation with the `new` operator. +<1> declare `int i`; assign a copy of `10` to `i` +<2> declare `int j`; assign a copy of `j` to `i` + +Assignment with reference types using the <>. -[source,Java] +[source,Painless] ---- -ArrayList l = new ArrayList();  // Declare an ArrayList variable l and set it - // to a newly allocated ArrayList -Map m = new HashMap(); // Declare a Map variable m and set it - // to a newly allocated HashMap +<1> ArrayList l = new ArrayList(); +<2> Map m = new HashMap(); ---- -Assigning a variable of one reference type to another variable of the same type. +<1> declare `ArrayList l`; assign a newly-allocated `Arraylist` to `l` +<2> declare `Map m`; assign a newly-allocated `HashMap` to `m` + with an implicit downcast -[source,Java] +Assignment of one variable to another using +<>. + +[source,Painless] ---- -List l = new ArrayList(); // Declare List variable l and set it a newly - // allocated ArrayList -List k = l;  // Declare List variable k and set it to the - // value of the List variable l -List m;                   // Declare List variable m and set it the - // default value null -m = k;                    // Set the value of List variable m to the value - // of List variable k +<1> List l = new ArrayList(); +<2> List k = l; +<3> List m; +<4> m = k; ---- + +<1> declare `List l`; assign a newly-allocated `Arraylist` to `l` + with an implicit downcast +<2> declare `List k`; assign a reference of `l` to `k` +<3> declare `List m`; +<4> assign a reference of `k` to `m` From 6729d5f821361bcccc3d9909cc7417159bb3cf23 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Wed, 18 Apr 2018 08:57:02 -0700 Subject: [PATCH 02/27] More docs. --- docs/painless/painless-comments.asciidoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/painless/painless-comments.asciidoc b/docs/painless/painless-comments.asciidoc index d1d2e47a143a6..04fec002a746f 100644 --- a/docs/painless/painless-comments.asciidoc +++ b/docs/painless/painless-comments.asciidoc @@ -1,12 +1,12 @@ [[painless-comments]] === Comments -Painless supports both single-line and multi-line comments. Comments can be -included anywhere within a script. Use the `//` token anywhere on a line to -specify a single-line comment. All characters from the `//` token to the end -of the line are ignored. Use an opening `/*` token and a closing `*/` token -to specify a multi-line comment. Multi-line comments can start anywhere on a -line, and all characters in between the `/*` token and `*/` token are ignored. +Use the `//` token anywhere on a line to specify a single-line comment. All +characters from the `//` token to the end of the line are ignored. Use an +opening `/*` token and a closing `*/` token to specify a multi-line comment. +Multi-line comments can start anywhere on a line, and all characters in between +the `/*` token and `*/` token are ignored. Comments can be included anywhere +within a script. *Grammar* [source,ANTLR4] From c2c34484efd9c811e1c0ff0a9aec7cc23378286d Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Wed, 18 Apr 2018 17:10:00 -0700 Subject: [PATCH 03/27] Modify language used to describe shallow copies. --- docs/painless/painless-variables.asciidoc | 41 ++++++++++------------- 1 file changed, 18 insertions(+), 23 deletions(-) diff --git a/docs/painless/painless-variables.asciidoc b/docs/painless/painless-variables.asciidoc index b63558f9a25ec..bf3c5437638d6 100644 --- a/docs/painless/painless-variables.asciidoc +++ b/docs/painless/painless-variables.asciidoc @@ -3,8 +3,9 @@ <> variables to <> values for <> in expressions. Specify variables as a -<>, <>, or -<> type. +<>, <>, or +<>. Variable operations follow the structure of a +standard JVM in relation to instruction execution and memory usage. [[declaration]] ==== Declaration @@ -12,10 +13,11 @@ Declare variables before use with the format of <> <>. Specify a comma-separated list of <> following the <> -to declare multiple variables in a single statement. Use -<> combined with a declaration statement to immediately -assign a value to a variable. Variables not immediately assigned a value will -have a default value assigned implicitly based on the <>. +to declare multiple variables in a single statement. Use an +<> statement combined with a declaration statement to +immediately assign a value to a variable. Variables not immediately assigned a +value will have a default value assigned implicitly based on the +<>. *Grammar* [source,ANTLR4] @@ -53,14 +55,7 @@ that produces a value can be assigned to any variable as long as the <> are the same or the resultant <> can be implicitly <> to the variable <>. Otherwise, an error will occur. - -Assignment of <> will cause the value to be -copied. Assignment of <> will cause the -value to be referred to with the exception of the <> -which is copied. Assignment of <> will -cause the value to be copied or referred to based on what the -<> represents. All types of assignment follow -the standard Java memory model. +<> values are shallow-copied when assigned. *Grammar* [source,ANTLR4] @@ -79,7 +74,7 @@ Variable assignment with an <>. ---- <1> declare `int i` -<2> assign a copy of `10` to `i` +<2> assign `10` to `i` <> combined with immediate variable assignment. @@ -89,8 +84,8 @@ Variable assignment with an <>. <2> double j = 2.0; ---- -<1> declare `int i`; assign a copy of `10` to `i` -<2> declare `double j`; assign a copy of `2.0` to `j` +<1> declare `int i`; assign `10` to `i` +<2> declare `double j`; assign `2.0` to `j` Assignment of one variable to another using <>. @@ -101,8 +96,8 @@ Assignment of one variable to another using <2> int j = i; ---- -<1> declare `int i`; assign a copy of `10` to `i` -<2> declare `int j`; assign a copy of `j` to `i` +<1> declare `int i`; assign `10` to `i` +<2> declare `int j`; assign `j` to `i` Assignment with reference types using the <>. @@ -114,7 +109,7 @@ Assignment with reference types using the <>. <1> declare `ArrayList l`; assign a newly-allocated `Arraylist` to `l` <2> declare `Map m`; assign a newly-allocated `HashMap` to `m` - with an implicit downcast + with an implicit cast to `Map` Assignment of one variable to another using <>. @@ -128,7 +123,7 @@ Assignment of one variable to another using ---- <1> declare `List l`; assign a newly-allocated `Arraylist` to `l` - with an implicit downcast -<2> declare `List k`; assign a reference of `l` to `k` + with an implicit cast to `List` +<2> declare `List k`; assign a shallow-copy of `l` to `k` <3> declare `List m`; -<4> assign a reference of `k` to `m` +<4> assign a shallow-copy of `k` to `m` From 1cdf013388f127bf8ed13ed1f891f96377a31cc6 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Wed, 18 Apr 2018 18:05:37 -0700 Subject: [PATCH 04/27] Move examples into lists to make sections flow better when multiple examples are used. --- docs/painless/painless-comments.asciidoc | 10 ++-- docs/painless/painless-identifiers.asciidoc | 4 +- docs/painless/painless-literals.asciidoc | 51 ++++++++++----------- docs/painless/painless-variables.asciidoc | 45 +++++++++--------- 4 files changed, 55 insertions(+), 55 deletions(-) diff --git a/docs/painless/painless-comments.asciidoc b/docs/painless/painless-comments.asciidoc index 04fec002a746f..588e464d97f78 100644 --- a/docs/painless/painless-comments.asciidoc +++ b/docs/painless/painless-comments.asciidoc @@ -17,17 +17,17 @@ MULTI_LINE_COMMENT: '/*' .*? '*/'; *Examples* -Single-line comments. - +* Single-line comments. ++ [source,Painless] ---- // single-line comment int value; // single-line comment ---- - -Multi-line comments. - ++ +* Multi-line comments. ++ [source,Painless] ---- /* multi- diff --git a/docs/painless/painless-identifiers.asciidoc b/docs/painless/painless-identifiers.asciidoc index 4b61b4f3d62ee..17073e3d4c415 100644 --- a/docs/painless/painless-identifiers.asciidoc +++ b/docs/painless/painless-identifiers.asciidoc @@ -14,8 +14,8 @@ ID: [_a-zA-Z] [_a-zA-Z-0-9]*; *Examples* -Variations of identifiers. - +* Variations of identifiers. ++ [source,Painless] ---- a diff --git a/docs/painless/painless-literals.asciidoc b/docs/painless/painless-literals.asciidoc index 191f3adb0c923..441cb264f1e15 100644 --- a/docs/painless/painless-literals.asciidoc +++ b/docs/painless/painless-literals.asciidoc @@ -24,8 +24,8 @@ HEX: '-'? '0' [xX] [0-9a-fA-F]+ [lL]?; *Examples* -Integer literals. - +* Integer literals. ++ [source,Painless] ---- <1> 0 @@ -35,7 +35,7 @@ Integer literals. <5> -022 <6> 0xF2A ---- - ++ <1> `int 0` <2> `double 0.0` <3> `long 1234` @@ -61,8 +61,8 @@ EXPONENT: ( [eE] [+\-]? [0-9]+ ); *Examples* -Floating point literals. - +* Floating point literals. ++ [source,Painless] ---- <1> 0.0 @@ -71,7 +71,7 @@ Floating point literals. <4> -126.34 <5> 89.9F ---- - ++ <1> `double 0.0` <2> `double 1000000.0` in exponent notation <3> `double 0.977777` @@ -81,12 +81,11 @@ Floating point literals. [[strings]] ==== Strings -Use string literals to specify string values of the -<> with either single-quotes or double-quotes. -Use a `\"` token to include a double-quote as part of a double-quoted string -literal. Use a `\'` token to include a single-quote as part of a single-quoted -string literal. Use a `\\` token to include a backslash as part of any string -literal. +Use string literals to specify <> values with +either single-quotes or double-quotes. Use a `\"` token to include a +double-quote as part of a double-quoted string literal. Use a `\'` token to +include a single-quote as part of a single-quoted string literal. Use a `\\` +token to include a backslash as part of any string literal. *Grammar* [source,ANTLR4] @@ -97,22 +96,22 @@ STRING: ( '"' ( '\\"' | '\\\\' | ~[\\"] )*? '"' ) *Examples* -String literals using single-quotes. - +* String literals using single-quotes. ++ [source,Painless] ---- 'single-quoted string literal' -'\'single-quoted string with escaped single-quotes\' and backslash \\' -'single-quoted string with non-escaped "double-quotes"' +'\'single-quoted with escaped single-quotes\' and backslash \\' +'single-quoted with non-escaped "double-quotes"' ---- - -String literals using double-quotes. - ++ +* String literals using double-quotes. ++ [source,Painless] ---- "double-quoted string literal" -"\"double-quoted string with escaped double-quotes\" and backslash: \\" -"double-quoted string with non-escaped 'single-quotes'" +"\"double-quoted with escaped double-quotes\" and backslash: \\" +"double-quoted with non-escaped 'single-quotes'" ---- [[characters]] @@ -126,16 +125,16 @@ or an error will occur. *Examples* -Casting string literals into <> values. - +* Casting string literals into <> values. ++ [source,Painless] ---- (char)"C" (char)'c' ---- - -Casting a <> value into a <> value. - ++ +* Casting a <> value into a <> value. ++ [source,Painless] ---- String s = "s"; diff --git a/docs/painless/painless-variables.asciidoc b/docs/painless/painless-variables.asciidoc index bf3c5437638d6..9756676a08b5b 100644 --- a/docs/painless/painless-variables.asciidoc +++ b/docs/painless/painless-variables.asciidoc @@ -29,8 +29,8 @@ assignment: '=' expression; *Examples* -Different variations of variable declaration. - +* Different variations of variable declaration. ++ [source,Painless] ---- <1> int x; @@ -39,7 +39,7 @@ Different variations of variable declaration. <4> def[] d; <5> int i = 10; ---- - ++ <1> declare a variable of type `int` and identifier `x` <2> declare a variable of type `List` and identifier `y` <3> declare three variables of type `int` and identifiers `x`, `y`, `z` @@ -65,55 +65,56 @@ assignment: ID '=' expression *Examples* -Variable assignment with an <>. - +* Variable assignment with an <>. ++ [source,Painless] ---- <1> int i; <2> i = 10; ---- - ++ <1> declare `int i` <2> assign `10` to `i` - -<> combined with immediate variable assignment. - ++ +* <> combined with immediate variable assignment. ++ [source,Painless] ---- <1> int i = 10; <2> double j = 2.0; ---- - ++ <1> declare `int i`; assign `10` to `i` <2> declare `double j`; assign `2.0` to `j` - -Assignment of one variable to another using ++ +* Assignment of one variable to another using <>. - ++ [source,Painless] ---- <1> int i = 10; <2> int j = i; ---- - ++ <1> declare `int i`; assign `10` to `i` <2> declare `int j`; assign `j` to `i` - -Assignment with reference types using the <>. - ++ +* Assignment with <> using the +<>. ++ [source,Painless] ---- <1> ArrayList l = new ArrayList(); <2> Map m = new HashMap(); ---- - ++ <1> declare `ArrayList l`; assign a newly-allocated `Arraylist` to `l` <2> declare `Map m`; assign a newly-allocated `HashMap` to `m` with an implicit cast to `Map` - -Assignment of one variable to another using ++ +* Assignment of one variable to another using <>. - ++ [source,Painless] ---- <1> List l = new ArrayList(); @@ -121,7 +122,7 @@ Assignment of one variable to another using <3> List m; <4> m = k; ---- - ++ <1> declare `List l`; assign a newly-allocated `Arraylist` to `l` with an implicit cast to `List` <2> declare `List k`; assign a shallow-copy of `l` to `k` From 862962be23ad4c162cd8a69d98d73054cae66781 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Thu, 19 Apr 2018 17:31:27 -0700 Subject: [PATCH 05/27] Update primitive types. --- docs/painless/painless-types.asciidoc | 228 ++++++++++++---------- docs/painless/painless-variables.asciidoc | 1 - 2 files changed, 122 insertions(+), 107 deletions(-) diff --git a/docs/painless/painless-types.asciidoc b/docs/painless/painless-types.asciidoc index 9d575a2069ae3..295706729edf2 100644 --- a/docs/painless/painless-types.asciidoc +++ b/docs/painless/painless-types.asciidoc @@ -1,124 +1,111 @@ [[painless-types]] === Types -Painless supports both dynamic and static types. Static types are split into -_primitive types_ and _reference types_. - -[[dynamic-types]] -==== Dynamic Types - -Painless supports one dynamic type: `def`. The `def` type can represent any -primitive or reference type. When you use the `def` type, it mimics the exact -behavior of whatever type it represents at runtime. The default value for the -def type is `null.` - -Internally, if the `def` type represents a primitive type, it is converted to the -corresponding reference type. It still behaves like the primitive type, however, -including within the casting model. The `def` type can be assigned to different -types during the course of script execution. - -IMPORTANT: Because a `def` type variable can be assigned to different types -during execution, type conversion errors that occur when using the `def` type -happen at runtime. - -Using the `def` type can have a slight impact on performance. If performance is -critical, it's better to declare static types. - -*Examples:* -[source,Java] ----- -def x = 1; // Declare def variable x and set it to the - // literal int 1 -def l = new ArrayList(); // Declare def variable l and set it a newly - // allocated ArrayList ----- +Types are a classification of data used to describe the properties of values +operated on in expressions and statements. These properties describe what data +the value can represent such as a number, string, or something more complex and +the rules for when a value is operated on. Types are split into the following +categories: <>, +<>, and <>. [[primitive-types]] ==== Primitive Types -Primitive types are allocated directly onto the stack according to the standard -Java memory model. - -Primitive types can behave as their corresponding (<>) -reference type. This means any piece of a reference type can be accessed or -called through the primitive type. Operations performed in this manner convert -the primitive type to its corresponding reference type at runtime and perform -the field access or method call without needing to perform any other -operations. - -Painless supports the following primitive types. - -byte:: -An 8-bit, signed, two's complement integer. -Range: [-128, 127]. -Default value: 0. -Reference type: Byte. - -short:: -A 16-bit, signed, two's complement integer. -Range: [-32768, 32767]. -Default value: 0. -Reference type: Short. - -char:: -A 16-bit Unicode character. -Range: [0, 65535]. -Default value: 0 or `\u0000`. -Reference type: Character. - -int:: -A 32-bit, signed, two's complement integer. -Range: [-2^32, 2^32-1]. -Default value: 0. -Reference type: Integer. - -long:: -A 64-bit, signed, two's complement integer. -Range: [-2^64, 2^64-1]. -Default value: 0. -Reference type: Long. - -float:: -A 32-bit, single-precision, IEEE 754 floating point number. -Range: Depends on multiple factors. -Default value: 0.0. -Reference type: Float. - -double:: -A 64-bit, double-precision, IEEE 754 floating point number. -Range: Depends on multiple factors. -Default value: 0.0. -Reference type: Double. - -boolean:: -A logical quanity with two possible values: true and false. -Range: true/false. -Default value: false. -Reference type: Boolean. - - -*Examples:* -[source,Java] +Primitive types are built directly into the JVM and are allocated to non-heap +memory. Primitive type values are deep-copied when <> +and when passed into <> or function as arguments. + +Primitive types have a corresponding <> (also +known as a <>). Any member of the corresponding +<> can be <> or +<> by executing the appropriate operation on the +primitive type value. Operations performed in this manner convert (box) the +primitive type value to its corresponding <> +value at runtime and execute the specified <> or +<>. + +The following primitive types are available: + +[horizontal] +`byte`:: +8-bit, signed, two's complement integer +* range: [`-128`, `127`] +* default value: `0` +* reference type: `Byte` + +`short`:: +16-bit, signed, two's complement integer +* range: [`-32768`, `32767`] +* default value: `0` +* reference type: `Short` + +`char`:: +16-bit, unsigned, Unicode character +* range: [`0`, `65535`] +* default value: `0` or `\u0000` +* reference type: `Character` + +`int`:: +32-bit, signed, two's complement integer +* range: [`-2^32`, `2^32-1`] +* default value: `0` +* reference type: `Integer` + +`long`:: +64-bit, signed, two's complement integer +* range: [`-2^64`, `2^64-1`] +* default value: `0` +* reference type: `Long` + +`float`:: +32-bit, signed, single-precision, IEEE 754 floating point number +* default value: `0.0` +* reference type: `Float` + +`double`:: +64-bit, signed, double-precision, IEEE 754 floating point number +* default value: `0.0` +* reference type: `Double` + +`boolean`:: +logical quanity with two possible values of `true` and `false` +* default value: `false` +* reference type: `Boolean` + +*Examples* + +* Primitive types used in <> and +<>. ++ +[source,Painless] ---- -int i = 1; // Declare variable i as an int and set it to the - // literal 1 -double d; // Declare variable d as a double and set it to the - // default value of 0.0 -boolean b = true; // Declare variable b as a boolean and set it to true +<1> int i = 1; +<2> double d; +<3> boolean b = true; ---- - -Using methods from the corresponding reference type on a primitive type. - -[source,Java] ++ +<1> declare `int i`; assign `1` to `i` +<2> declare `double d` +<3> declare `boolean b`; assign `true` to `b` ++ +* Method call on a primitive type from the corresponding +<>. ++ +[source,Painless] ---- -int i = 1; // Declare variable i as an int and set it to the - // literal 1 -i.toString(); // Invokes the Integer method toString on variable i +<1> int i = 1; +<2> i.toString(); ---- ++ +<1> declare `int i`; assign `1` to `i` +<2> implicitly convert (box) `i` to the reference type `Integer`; +invoke the `Integer` method `toString` on the converted (boxed) value [[reference-types]] ==== Reference Types +<> values are shallow-copied when assigned. + Reference types are similar to Java classes and can contain multiple pieces known as _members_. However, reference types do not support access modifiers. You allocate reference type instances on the heap using the `new` operator. @@ -184,6 +171,35 @@ Integer.MAX_VALUE // a static field access Long.parseLong("123L") // a static function call ---- +[[dynamic-types]] +==== Dynamic Types + +Painless supports one dynamic type: `def`. The `def` type can represent any +primitive or reference type. When you use the `def` type, it mimics the exact +behavior of whatever type it represents at runtime. The default value for the +def type is `null.` + +Internally, if the `def` type represents a primitive type, it is converted to the +corresponding reference type. It still behaves like the primitive type, however, +including within the casting model. The `def` type can be assigned to different +types during the course of script execution. + +IMPORTANT: Because a `def` type variable can be assigned to different types +during execution, type conversion errors that occur when using the `def` type +happen at runtime. + +Using the `def` type can have a slight impact on performance. If performance is +critical, it's better to declare static types. + +*Examples:* +[source,Java] +---- +def x = 1; // Declare def variable x and set it to the + // literal int 1 +def l = new ArrayList(); // Declare def variable l and set it a newly + // allocated ArrayList +---- + [[string-type]] ==== String Type diff --git a/docs/painless/painless-variables.asciidoc b/docs/painless/painless-variables.asciidoc index 9756676a08b5b..546e3928f466c 100644 --- a/docs/painless/painless-variables.asciidoc +++ b/docs/painless/painless-variables.asciidoc @@ -55,7 +55,6 @@ that produces a value can be assigned to any variable as long as the <> are the same or the resultant <> can be implicitly <> to the variable <>. Otherwise, an error will occur. -<> values are shallow-copied when assigned. *Grammar* [source,ANTLR4] From 73883ac0f41e9dc3a18b05e7c5e61efbfeb2fc81 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Mon, 23 Apr 2018 18:13:51 -0700 Subject: [PATCH 06/27] Cleaned up reference types. --- docs/painless/painless-types.asciidoc | 177 ++++++++++++++-------- docs/painless/painless-variables.asciidoc | 30 ++-- 2 files changed, 134 insertions(+), 73 deletions(-) diff --git a/docs/painless/painless-types.asciidoc b/docs/painless/painless-types.asciidoc index 295706729edf2..1b2948bfc430a 100644 --- a/docs/painless/painless-types.asciidoc +++ b/docs/painless/painless-types.asciidoc @@ -11,9 +11,10 @@ categories: <>, [[primitive-types]] ==== Primitive Types -Primitive types are built directly into the JVM and are allocated to non-heap -memory. Primitive type values are deep-copied when <> -and when passed into <> or function as arguments. +Primitive types are built straight into the JVM, directly contain their data, +and are allocated to non-heap memory. Primitive type values are copied when +<> and when passed into a <> or +function as arguments. Primitive types have a corresponding <> (also known as a <>). Any member of the corresponding @@ -85,7 +86,7 @@ logical quanity with two possible values of `true` and `false` ---- + <1> declare `int i`; assign `1` to `i` -<2> declare `double d` +<2> declare `double d`; assign the default value of `0.0` to `d` <3> declare `boolean b`; assign `true` to `b` + * Method call on a primitive type from the corresponding @@ -104,72 +105,124 @@ invoke the `Integer` method `toString` on the converted (boxed) value [[reference-types]] ==== Reference Types -<> values are shallow-copied when assigned. - -Reference types are similar to Java classes and can contain multiple pieces -known as _members_. However, reference types do not support access modifiers. -You allocate reference type instances on the heap using the `new` operator. - -Reference types can have both static and non-static members: - -* Static members are shared by all instances of the same reference type and -can be accessed without allocating an instance of the reference type. For -example `Integer.MAX_VALUE`. -* Non-static members are specific to an instance of the reference type -and can only be accessed through the allocated instance. - -The default value for a reference type is `null`, indicating that no memory has -been allocated for it. When you assign `null` to a reference type, its previous -value is discarded and garbage collected in accordance with the Java memory -model as long as there are no other references to that value. - -A reference type can contain: - -* Zero to many primitive types. Primitive type members can be static or -non-static and read-only or read-write. -* Zero to many reference types. Reference type members can be static or -non-static and read-only or read-write. -* Methods that call an internal function to return a value and/or manipulate -the primitive or reference type members. Method members can be static or -non-static. -* Constructors that call an internal function to return a newly-allocated -reference type instance. Constructors are non-static methods that can -optionally manipulate the primitive and reference type members. - -Reference types support a Java-style inheritance model. Consider types A and B. -Type A is considered to be a parent of B, and B a child of A, if B inherits -(is able to access as its own) all of A's fields and methods. Type B is +Reference types are constructs (objects), potentially representing multiple +pieces of data (member fields) and logic to manipulate that data (member +methods), defined as part of the application programming interface (API) for +use in scripts. + +A reference type instance is a single set of data for one reference type +object allocated to the heap. A reference type instance is allocated using the +<>. + +Reference type values refer to reference type instances, and multiple reference +type values may refer to a single reference type instance. A change to a +reference type instance will affect all reference type values refering to that +instance. Reference type values are shallow-copied when +<> and when passed into a <> or +function as arguments. + +The default value for a <> reference type value is +`null`. <> a <> reference +type instance or <> an existing reference type instance to a +reference type value for <> later in a script. +<> `null` to a reference type value to indicate the +reference type value refers to no reference type instance. A reference type +instance will be garbage collected by the JVM when no reference type values refer +to that reference type instance. + +Reference type objects can contain member fields, member methods, and +constructors. Member fields are named and typed pieces of data that are read +and written to using the <>. Member methods are +functions decicated to a single reference type object that can manipulate +member fields and return values. Call member methods using the +<>. Constructors are a special type of function +used to allocate a reference type instance using the +<>. + +Reference type objects can have both static and non-static members (member +fields and member methods). <> and +<> static members of a reference type object without +allocating a reference type instance using the reference type object name +as the <> in place of a reference type value. +Static members are singletons per reference type object. Non-static members are +specific to a reference type instance. <> and +<> non-static members on a reference type value referring +to an allocated reference type instance. + +A reference type can contain the following: + +* zero to many <> static member fields +* zero to many <> non-static member fields +* zero to many reference type static member fields +* zero to many reference type non-static member fields +* zero to many <> static member fields +* zero to many <> non-static member fields +* zero to many static member methods +* zero to many non-static member methods +* zero to many constructors + +Reference type objects support a basic inheritance model. Consider types A and +B. Type A is considered to be a parent of B, and B a child of A, if B inherits +(is able to access as its own) all of A's non-static members. Type B is considered a descendant of A if there exists a recursive parent-child relationship from B to A with none to many types in between. In this case, B -inherits all of A's fields and methods along with all of the fields and -methods of the types in between. Type B is also considered to be a type A -in both relationships. +inherits all of A's non-static members along with all of the non-static members +of the types in between. Type B is also considered to be a type A in both +relationships. -For the complete list of Painless reference types and their supported methods, -see the https://www.elastic.co/guide/en/elasticsearch/reference/current/painless-api-reference.html[Painless API Reference]. - -For more information about working with reference types, see -<> and <>. +*Examples* -*Examples:* -[source,Java] +* Reference types used in several different <>. ++ +[source,Painless] ---- -ArrayList al = new ArrayList(); // Declare variable al as an ArrayList and - // set it to a newly allocated ArrayList -List l = new ArrayList(); // Declare variable l as a List and set - // it to a newly allocated ArrayList, which is - // allowed because ArrayList inherits from List -Map m; // Declare variable m as a Map and set it - // to the default value of null +<1> List l = new ArrayList(); +<2> l.add(1); +<3> int i = l.get(0) + 2; ---- - -Directly accessing static pieces of a reference type. - -[source,Java] ++ +<1> declare `List l`; + assign a new `ArrayList` to `l` +<2> call non-static member method `add` on l with arguments of `1` +<3> declare `int i`; + call non-static member method `get` on `l` with arguments `0`; + add `1` to `2`; + assign `3` to `i` ++ +* Sharing a reference type instance. ++ +[source,Painless] +---- +<1> List l0 = new ArrayList(); +<2> List l1 = l0; +<3> l0.add(1); +<4> l1.add(2); +<5> int i = l1.get(0) + l0.get(1); +---- ++ +<1> declare `List l0`; + assign a new `ArrayList` to `l0` +<2> declare `List l1`; + assign a shallow-copy of `l0` to `l1` +<3> call non-static member method `add` on l0 with arguments of `1` +<4> call non-static member method `add` on l1 with arguments of `2` +<5> note `l0` and `l1` refer to the same reference type instance; + call non-static member method `get` on `l1` with arguments `0`; + call non-static member method `get` on `l0` with arguments `1`; + add `1` to `2`; + assign `3` to `i`; ++ +* Using the static members of a reference type. ++ +[source,Painless] ---- -Integer.MAX_VALUE // a static field access -Long.parseLong("123L") // a static function call +<1> Integer.MAX_VALUE +<2> Long.parseLong("123L") ---- ++ +<1> access static field `MAX_VALUE` on reference type `Integer` +<2> call static member method `parseLong` on reference type `Long` with + arguments `long 123` [[dynamic-types]] ==== Dynamic Types diff --git a/docs/painless/painless-variables.asciidoc b/docs/painless/painless-variables.asciidoc index 546e3928f466c..c9461f9c88b5e 100644 --- a/docs/painless/painless-variables.asciidoc +++ b/docs/painless/painless-variables.asciidoc @@ -72,7 +72,8 @@ assignment: ID '=' expression <2> i = 10; ---- + -<1> declare `int i` +<1> declare `int i`; + assign default value `0` to `i` <2> assign `10` to `i` + * <> combined with immediate variable assignment. @@ -83,8 +84,10 @@ assignment: ID '=' expression <2> double j = 2.0; ---- + -<1> declare `int i`; assign `10` to `i` -<2> declare `double j`; assign `2.0` to `j` +<1> declare `int i`; + assign `10` to `i` +<2> declare `double j`; + assign `2.0` to `j` + * Assignment of one variable to another using <>. @@ -95,8 +98,10 @@ assignment: ID '=' expression <2> int j = i; ---- + -<1> declare `int i`; assign `10` to `i` -<2> declare `int j`; assign `j` to `i` +<1> declare `int i`; + assign `10` to `i` +<2> declare `int j`; + assign `j` to `i` + * Assignment with <> using the <>. @@ -107,9 +112,10 @@ assignment: ID '=' expression <2> Map m = new HashMap(); ---- + -<1> declare `ArrayList l`; assign a newly-allocated `Arraylist` to `l` -<2> declare `Map m`; assign a newly-allocated `HashMap` to `m` - with an implicit cast to `Map` +<1> declare `ArrayList l`; + assign a newly-allocated `Arraylist` to `l` +<2> declare `Map m`; + assign a newly-allocated `HashMap` to `m` with an implicit cast to `Map` + * Assignment of one variable to another using <>. @@ -122,8 +128,10 @@ assignment: ID '=' expression <4> m = k; ---- + -<1> declare `List l`; assign a newly-allocated `Arraylist` to `l` - with an implicit cast to `List` -<2> declare `List k`; assign a shallow-copy of `l` to `k` +<1> declare `List l`; + assign a newly-allocated `Arraylist` to `l` with an implicit cast to `List` +<2> declare `List k`; + assign a shallow-copy of `l` to `k` <3> declare `List m`; + assign default value `null` to `m` <4> assign a shallow-copy of `k` to `m` From 7dfb034996bccb635809db0e714550d18fa41737 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Tue, 24 Apr 2018 13:35:08 -0700 Subject: [PATCH 07/27] Clean up dynamic types. --- docs/painless/painless-types.asciidoc | 72 ++++++++++++++++----------- 1 file changed, 42 insertions(+), 30 deletions(-) diff --git a/docs/painless/painless-types.asciidoc b/docs/painless/painless-types.asciidoc index 1b2948bfc430a..fe5a399957cce 100644 --- a/docs/painless/painless-types.asciidoc +++ b/docs/painless/painless-types.asciidoc @@ -16,14 +16,14 @@ and are allocated to non-heap memory. Primitive type values are copied when <> and when passed into a <> or function as arguments. -Primitive types have a corresponding <> (also +Primitive types have corresponding <> (also known as a <>). Any member of the corresponding <> can be <> or <> by executing the appropriate operation on the -primitive type value. Operations performed in this manner convert (box) the -primitive type value to its corresponding <> -value at runtime and execute the specified <> or -<>. +primitive type value. Operations performed in this manner convert +(<>) the primitive type value to its corresponding +<> value at runtime and execute the specified +<> or <>. The following primitive types are available: @@ -121,14 +121,15 @@ instance. Reference type values are shallow-copied when <> and when passed into a <> or function as arguments. -The default value for a <> reference type value is -`null`. <> a <> reference -type instance or <> an existing reference type instance to a -reference type value for <> later in a script. -<> `null` to a reference type value to indicate the +The default value for a <> reference type +<> is `null`. <> a +<> reference type instance or +<> an existing reference type instance to a reference type +<> for <> later in a +script. <> `null` to a reference type value to indicate the reference type value refers to no reference type instance. A reference type -instance will be garbage collected by the JVM when no reference type values refer -to that reference type instance. +instance will be garbage collected by the JVM when no reference type values +refer to that reference type instance. Reference type objects can contain member fields, member methods, and constructors. Member fields are named and typed pieces of data that are read @@ -227,31 +228,42 @@ relationships. [[dynamic-types]] ==== Dynamic Types -Painless supports one dynamic type: `def`. The `def` type can represent any -primitive or reference type. When you use the `def` type, it mimics the exact -behavior of whatever type it represents at runtime. The default value for the -def type is `null.` +Dynamic types can represent values of any primitive type or reference type +under a single type name `def`. The `def` type mimics the behavior of whatever +value is currently represented. -Internally, if the `def` type represents a primitive type, it is converted to the -corresponding reference type. It still behaves like the primitive type, however, -including within the casting model. The `def` type can be assigned to different -types during the course of script execution. +Internally, if a `def` type value is a primitive type value, the value is +converted (<>) to the corresponding reference type +instance. However, the `def` type still behaves like the primitive type +including within the <>. -IMPORTANT: Because a `def` type variable can be assigned to different types -during execution, type conversion errors that occur when using the `def` type -happen at runtime. +The default value for a <> `def` type +<> is `null`. A `def` type +<> can have different types +<> throughout a script. -Using the `def` type can have a slight impact on performance. If performance is -critical, it's better to declare static types. +<> using the `def` type will generate +errors at *runtime* if an inappropriate type is used. Using the `def` type can +have a slight impact on performance. Use only primitive types and reference +types directly when performance is critical. -*Examples:* +*Examples* + +* General uses of the `def` type. ++ [source,Java] ---- -def x = 1; // Declare def variable x and set it to the - // literal int 1 -def l = new ArrayList(); // Declare def variable l and set it a newly - // allocated ArrayList +<1> def i = 1; +<2> def l = new ArrayList(); +<3> l = i; ---- ++ +<1> declare `def i`; + assign `1` to `i` +<2> declare `def l`; + assign a new `ArrayList` to `l` +<3> assign `i` to `l`; + note the switch in type from `ArrayList` to `int` [[string-type]] ==== String Type From 75f14989df9b1539245e7a555f518b994123959e Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Wed, 25 Apr 2018 09:34:20 -0700 Subject: [PATCH 08/27] String and void type clean up. --- docs/painless/painless-types.asciidoc | 71 +++++++++++++++------------ 1 file changed, 40 insertions(+), 31 deletions(-) diff --git a/docs/painless/painless-types.asciidoc b/docs/painless/painless-types.asciidoc index fe5a399957cce..cf08697f00aa3 100644 --- a/docs/painless/painless-types.asciidoc +++ b/docs/painless/painless-types.asciidoc @@ -85,9 +85,12 @@ logical quanity with two possible values of `true` and `false` <3> boolean b = true; ---- + -<1> declare `int i`; assign `1` to `i` -<2> declare `double d`; assign the default value of `0.0` to `d` -<3> declare `boolean b`; assign `true` to `b` +<1> declare `int i`; + assign `1` to `i` +<2> declare `double d`; + assign the default value of `0.0` to `d` +<3> declare `boolean b`; + assign `true` to `b` + * Method call on a primitive type from the corresponding <>. @@ -98,9 +101,10 @@ logical quanity with two possible values of `true` and `false` <2> i.toString(); ---- + -<1> declare `int i`; assign `1` to `i` +<1> declare `int i`; + assign `1` to `i` <2> implicitly convert (box) `i` to the reference type `Integer`; -invoke the `Integer` method `toString` on the converted (boxed) value + call the non-static member method `toString` on the converted (boxed) value [[reference-types]] ==== Reference Types @@ -112,7 +116,7 @@ use in scripts. A reference type instance is a single set of data for one reference type object allocated to the heap. A reference type instance is allocated using the -<>. +<>. Reference type values refer to reference type instances, and multiple reference type values may refer to a single reference type instance. A change to a @@ -138,7 +142,7 @@ functions decicated to a single reference type object that can manipulate member fields and return values. Call member methods using the <>. Constructors are a special type of function used to allocate a reference type instance using the -<>. +<>. Reference type objects can have both static and non-static members (member fields and member methods). <> and @@ -184,7 +188,7 @@ relationships. + <1> declare `List l`; assign a new `ArrayList` to `l` -<2> call non-static member method `add` on l with arguments of `1` +<2> call non-static member method `add` on `l` with arguments of `1` <3> declare `int i`; call non-static member method `get` on `l` with arguments `0`; add `1` to `2`; @@ -243,15 +247,15 @@ The default value for a <> `def` type <> throughout a script. <> using the `def` type will generate -errors at *runtime* if an inappropriate type is used. Using the `def` type can -have a slight impact on performance. Use only primitive types and reference -types directly when performance is critical. +errors at runtime if an inappropriate type is represented. Using the `def` +type can have a slight impact on performance. Use only primitive types and +reference types directly when performance is critical. *Examples* * General uses of the `def` type. + -[source,Java] +[source,Painless] ---- <1> def i = 1; <2> def l = new ArrayList(); @@ -268,33 +272,38 @@ types directly when performance is critical. [[string-type]] ==== String Type -A `String` is a specialized reference type that is immutable and does not have -to be explicitly allocated. You can directly assign to a `String` without first -allocating it with the `new` keyword. (Strings can be allocated with the `new` -keyword, but it's not required.) +The `String` type is a specialized reference type that does not require +explicit allocation. Use <> to directly +<> or <> on `String` values. +While not required, the <> can allocate +`String` values. -When assigning a value to a `String`, you must enclose the text in single or -double quotes. Strings are allocated according to the standard Java Memory Model. -The default value for a `String` is `null.` +*Examples* +[source,Painless] -*Examples:* -[source,Java] +* General use of the `String` type. ++ ---- -String r = "some text"; // Declare String r and set it to the - // String "some text" -String s = 'some text'; // Declare String s and set it to the - // String 'some text' -String t = new String("some text"); // Declare String t and set it to the - // String "some text" -String u; // Declare String u and set it to the - // default value null +<1> String r = "some text"; +<2> String s = 'some text'; +<3> String t = new String("some text"); +<4> String u; ---- ++ +<1> declare `String r`; + assign `"some text"` to `r` +<2> declare `String s`; + assign `'some text'` to `s` +<3> declare `String t`; + assign new `String` with arguments `"some text"` to `t` +<4> declare `String u`; + assign the default value of `null` to `u` [[void-type]] ==== void Type -The `void` type represents the concept of no type. In Painless, `void` declares -that a function has no return value. +The `void` type represents the concept of a lack of type. The `void` type is +primarily used to indicate a function will return no value. [[array-type]] ==== Array Type From bce78ed2c9b290ba6d78a142ba2367e1b7c6298a Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Sat, 28 Apr 2018 12:40:49 -0700 Subject: [PATCH 09/27] Fixes. --- docs/painless/painless-types.asciidoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/painless/painless-types.asciidoc b/docs/painless/painless-types.asciidoc index cf08697f00aa3..3825c13cd407a 100644 --- a/docs/painless/painless-types.asciidoc +++ b/docs/painless/painless-types.asciidoc @@ -69,7 +69,7 @@ The following primitive types are available: * reference type: `Double` `boolean`:: -logical quanity with two possible values of `true` and `false` +logical quantity with two possible values of `true` and `false` * default value: `false` * reference type: `Boolean` @@ -308,6 +308,9 @@ primarily used to indicate a function will return no value. [[array-type]] ==== Array Type +Array types are a specialized reference type that contain a series of elements + + Arrays contain a series of elements of the same type that can be allocated simultaneously. Painless supports both single and multi-dimensional arrays for all types except void (including `def`). From e82a1e0eb523ce5d413726ba0023af62fd65cc84 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Mon, 30 Apr 2018 17:02:01 -0700 Subject: [PATCH 10/27] Clean up types section. --- docs/painless/painless-operators.asciidoc | 46 ++++++++- docs/painless/painless-types.asciidoc | 114 +++++++++++++--------- docs/painless/painless-variables.asciidoc | 48 +++++++-- 3 files changed, 149 insertions(+), 59 deletions(-) diff --git a/docs/painless/painless-operators.asciidoc b/docs/painless/painless-operators.asciidoc index 915d811fa441b..d80a6699680e0 100644 --- a/docs/painless/painless-operators.asciidoc +++ b/docs/painless/painless-operators.asciidoc @@ -240,6 +240,7 @@ operator. See Function Calls [MARK] for more information. The brackets operator `[]` is used to create and access arrays, lists, and maps. The braces operator `{}` is used to intialize arrays. +[[array-initialization]] ===== Creating and Initializing Arrays You create and initialize arrays using the brackets `[]` and braces `{}` @@ -248,9 +249,49 @@ initialize each dimension with are specified as a comma-separated list enclosed in braces. For example, `new int[] {1, 2, 3}` creates a one dimensional `int` array with a size of 3 and the values 1, 2, and 3. -For more information about allocating and initializing arrays, see <>. +To allocate an array, you use the `new` keyword followed by the type and a +set of brackets for each dimension. You can explicitly define the size of each dimension by specifying an expression within the brackets, or initialize each +dimension with the desired number of values. The allocated size of each +dimension is its permanent size. +To initialize an array, specify the values you want to initialize +each dimension with as a comma-separated list of expressions enclosed in braces. +For example, `new int[] {1, 2, 3}` creates a one-dimensional `int` array with a +size of 3 and the values 1, 2, and 3. + +When you initialize an array, the order of the expressions is maintained. Each expression used as part of the initialization is converted to the +array's type. An error occurs if the types do not match. + +*Grammar:* +[source,ANTLR4] +---- +declare_array: TYPE ('[' ']')+; + +array_initialization: 'new' TYPE '[' ']' '{' expression (',' expression) '}' + | 'new' TYPE '[' ']' '{' '}'; +---- + +*Examples:* +[source,Java] +---- +int[] x = new int[5]; // Declare int array x and assign it a newly + // allocated int array with a size of 5 +def[][] y = new def[5][5]; // Declare the 2-dimensional def array y and + // assign it a newly allocated 2-dimensional + // array where both dimensions have a size of 5 +int[] x = new int[] {1, 2, 3}; // Declare int array x and set it to an int + // array with values 1, 2, 3 and a size of 3 +int i = 1; +long l = 2L; +float f = 3.0F; +double d = 4.0; +String s = "5"; +def[] da = new def[] {i, l, f*d, s}; // Declare def array da and set it to + // a def array with a size of 4 and the + // values i, l, f*d, and s +---- + +[[array-access]] ===== Accessing Array Elements Elements in an array are stored and accessed using the brackets `[]` operator. @@ -727,6 +768,7 @@ def e; // declares the def variable e e = new HashMap(m); // sets e to a newly allocated HashMap using the constructor with a single argument m ---- +[[new-array]] ==== New Array An array type instance can be allocated using the new operator. The format starts with the new operator followed by the type followed by a series of opening and closing braces each containing an expression for the size of the dimension. diff --git a/docs/painless/painless-types.asciidoc b/docs/painless/painless-types.asciidoc index 3825c13cd407a..c936d903ffdf1 100644 --- a/docs/painless/painless-types.asciidoc +++ b/docs/painless/painless-types.asciidoc @@ -120,7 +120,7 @@ object allocated to the heap. A reference type instance is allocated using the Reference type values refer to reference type instances, and multiple reference type values may refer to a single reference type instance. A change to a -reference type instance will affect all reference type values refering to that +reference type instance will affect all reference type values referring to that instance. Reference type values are shallow-copied when <> and when passed into a <> or function as arguments. @@ -279,10 +279,10 @@ While not required, the <> can allocate `String` values. *Examples* -[source,Painless] * General use of the `String` type. + +[source,Painless] ---- <1> String r = "some text"; <2> String s = 'some text'; @@ -305,58 +305,76 @@ While not required, the <> can allocate The `void` type represents the concept of a lack of type. The `void` type is primarily used to indicate a function will return no value. -[[array-type]] -==== Array Type - -Array types are a specialized reference type that contain a series of elements - - -Arrays contain a series of elements of the same type that can be allocated -simultaneously. Painless supports both single and multi-dimensional arrays for -all types except void (including `def`). +*Examples* -You declare an array by specifying a type followed by a series of empty brackets, -where each set of brackets represents a dimension. Declared arrays have a default -value of `null` and are themselves a reference type. +* Use of the `void` type in a function. ++ +[source,Painless] +---- +void addToList(List l, def d) { + l.add(d); +} +---- -To allocate an array, you use the `new` keyword followed by the type and a -set of brackets for each dimension. You can explicitly define the size of each dimension by specifying an expression within the brackets, or initialize each -dimension with the desired number of values. The allocated size of each -dimension is its permanent size. +[[array-type]] +==== Array Type -To initialize an array, specify the values you want to initialize -each dimension with as a comma-separated list of expressions enclosed in braces. -For example, `new int[] {1, 2, 3}` creates a one-dimensional `int` array with a -size of 3 and the values 1, 2, and 3. +The array type is a specialized reference type where an array type instance +represents a series of values. All values in an array type instance are of +the same type. Each value is assigned an index from within the range +`[0, length)` where length is the total number of values allocated for the +array type instance. Specify the type of values and the length during an +array allocation. + +Allocate an array type instance using the <> or the +<>. Array type instances are +allocated to the heap. <> and <> +array type variables for <> within scripts. The +default value for newly-declared array instance types is `null`. Array type +values are shallow-copied when <> and when passed into a +<> or function as arguments. Read and write to individual +values within the array type instance using the <>. + +When an array type instance is allocated with multiple dimensions using the +range `[2, d]` where `d >= 2`, each dimension in the range `[1, d-1]` is also +an array type. The array type of each dimension, `n`, is an array type with the +number of dimensions equal to `d-n`. For example, consider `int[][][]` with 3 +dimensions. The 3rd dimension, `d-3`, is the primitive type `int`. The 2nd +dimension, `d-2`, is the array type `int[]`. And the 1st dimension, `d-1` is +the array type `int[][]`. -When you initialize an array, the order of the expressions is maintained. Each expression used as part of the initialization is converted to the -array's type. An error occurs if the types do not match. +*Examples* -*Grammar:* -[source,ANTLR4] +* General use of single-dimensional arrays. ++ +[source,Painless] ---- -declare_array: TYPE ('[' ']')+; - -array_initialization: 'new' TYPE '[' ']' '{' expression (',' expression) '}' - | 'new' TYPE '[' ']' '{' '}'; +<1> int[] x; +<2> float[] y = new float[10]; +<3> def z = new float[5]; +<4> y[9] = 1.0F; +<5> z[0] = y[9]; ---- - -*Examples:* -[source,Java] ++ +<1> declare `int[] x` +<2> declare `float[] y`; + assign a newly-allocated array type of `float` to `y` +<3> declare `def z`; + assign a newly-allocated array type of `float` to `z` +<4> assign `1.0F` to the 9th index of `y` +<5> assign the value of 9th index of `y` to the 0th index of `z` ++ +* Use of a multi-dimensional array. ++ +[source,Painless] ---- -int[] x = new int[5]; // Declare int array x and assign it a newly - // allocated int array with a size of 5 -def[][] y = new def[5][5]; // Declare the 2-dimensional def array y and - // assign it a newly allocated 2-dimensional - // array where both dimensions have a size of 5 -int[] x = new int[] {1, 2, 3}; // Declare int array x and set it to an int - // array with values 1, 2, 3 and a size of 3 -int i = 1; -long l = 2L; -float f = 3.0F; -double d = 4.0; -String s = "5"; -def[] da = new def[] {i, l, f*d, s}; // Declare def array da and set it to - // a def array with a size of 4 and the - // values i, l, f*d, and s +<1> int[][][] ia3 = new int[2][3][4]; +<2> ia3[1][2][3] = 99; +<3> int i = ia3[1][2][3]; ---- ++ +<1> declare `int[][][] ia`; + assign a newly-allocated 3-dimensional array type of `int` to `ia3` +<2> assign `99` to the 3rd index of the 2nd index of the 1st index of `ia3` +<3> assign the value of the 3rd index of the 2nd index of the 1st index + of `ia3` to `i` \ No newline at end of file diff --git a/docs/painless/painless-variables.asciidoc b/docs/painless/painless-variables.asciidoc index c9461f9c88b5e..08d4f58a82323 100644 --- a/docs/painless/painless-variables.asciidoc +++ b/docs/painless/painless-variables.asciidoc @@ -11,13 +11,15 @@ standard JVM in relation to instruction execution and memory usage. ==== Declaration Declare variables before use with the format of <> -<>. Specify a comma-separated list of -<> following the <> -to declare multiple variables in a single statement. Use an -<> statement combined with a declaration statement to -immediately assign a value to a variable. Variables not immediately assigned a -value will have a default value assigned implicitly based on the -<>. +<>. Declare <> +variables using an opening `[` token and a closing `]` token for each +dimension directly after the <>. Specify a +comma-separated list of <> following the +<> to declare multiple variables in a single statement. +Use an <> statement combined with a declaration +statement to immediately assign a value to a variable. Variables not +immediately assigned a value will have a default value assigned implicitly +based on the <>. *Grammar* [source,ANTLR4] @@ -36,16 +38,20 @@ assignment: '=' expression; <1> int x; <2> List y; <3> int x, y, z; -<4> def[] d; +<4> def d; <5> int i = 10; +<6> float[] f; +<7> Map[][] m; ---- + <1> declare a variable of type `int` and identifier `x` <2> declare a variable of type `List` and identifier `y` <3> declare three variables of type `int` and identifiers `x`, `y`, `z` -<4> declare a variable of type `def[]` and identifier `d` +<4> declare a variable of type `def` and identifier `d` <5> declare a variable of type `int` and identifier `i`; assign the integer literal `10` to `i` +<6> declare a 1-dimensional array type variable of `float` and identifier `f` +<7> declare a 2-dimensional array type variable of `Map` and identifier `m` [[assignment]] ==== Assignment @@ -135,3 +141,27 @@ assignment: ID '=' expression <3> declare `List m`; assign default value `null` to `m` <4> assign a shallow-copy of `k` to `m` ++ +* Assignment with the <> using the +<>. ++ +[source,Painless] +---- +<1> int[] ia1; +<2> ia1 = new int[2]; +<3> ia1[0] = 1; +<4> int[] ib1 = ia1; +<5> int[][] ic2 = new int[2][5]; +<6> ic2[0][0] = 2; +<7> ic2[0] = ia1; +---- ++ +<1> declare `int[] ia1` +<2> assign a newly-allocated 1-dimensional array type of `int` to `ia1` +<3> assign `1` to the 0th index of `ia1` +<4> declare `int[] ib1`; + assign a shallow-copy of `ia1` to `ib1` +<5> declare `int[][] ic2`; + assign a newly-allocated 2-dimensional array type of `int` to `ic2` +<6> assign `2` to the 0th index of the 0th index of `ic2` +<7> assign a shallow-copy of `ia1` to the 0th index of `ic2` \ No newline at end of file From 8bc0c748f0edacbd0d5782bc79cc855136b01f10 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Thu, 3 May 2018 17:12:31 -0700 Subject: [PATCH 11/27] Some casting and example clean up. --- docs/painless/painless-casting.asciidoc | 129 +++++++++++++++------- docs/painless/painless-types.asciidoc | 45 ++++---- docs/painless/painless-variables.asciidoc | 65 ++++++----- 3 files changed, 150 insertions(+), 89 deletions(-) diff --git a/docs/painless/painless-casting.asciidoc b/docs/painless/painless-casting.asciidoc index ec4f9919bd043..e7b90e94c1884 100644 --- a/docs/painless/painless-casting.asciidoc +++ b/docs/painless/painless-casting.asciidoc @@ -1,65 +1,110 @@ [[painless-casting]] === Casting -Casting is the conversion of one type to another. Implicit casts are casts that -occur automatically, such as during an assignment operation. Explicit casts are -casts where you use the casting operator to explicitly convert one type to -another. This is necessary during operations where the cast cannot be inferred. - -To cast to a new type, precede the expression by the new type enclosed in -parentheses, for example -`(int)x`. - -The following sections specify the implicit casts that can be performed and the -explicit casts that are allowed. The only other permitted cast is casting -a single character `String` to a `char`. - -*Grammar:* +A cast is the conversion of the value of one type to the equivalent value of an +inferred or specified type. Implicit casts are an inferred operation that +automatically convert values between types within a statement or +<> when necessary. Explicit casts are a +specified operation that forcefully convert values between types and are +required when an appropriate type for a statement or +<> cannot be inferred. If there exists no +equivalent value for the type converted to during a cast operation an error +will occur. If an implicit cast is given but an explicit cast is required an +error will occur. + +*Grammar* [source,ANTLR4] ---- cast: '(' TYPE ')' expression ---- +*Examples* + +* General casts. ++ +[source,Painless] +---- +<1> int i = (int)5L; +<2> Map m = new HashMap(); +<3> HashMap hm = (HashMap)m; +---- ++ +<1> declare `int i`; + explicitly cast `long 5` to `int`; + assign `5` to `i` +<2> declare `Map m`; + implicit cast new `HashMap` to `Map`; + assign `Map` value to `m` +<3> declare `HashMap hm`; + explicit cast `Map m` to `HashMap`; + assign `Map` value to `hm` + [[numeric-casting]] ==== Numeric Casting -The following table shows the allowed implicit and explicit casts between -numeric types. Read the table by row. To find out if you need to explicitly -cast from type A to type B, find the row for type A and scan across to the -column for type B. +A numeric cast is the conversion of the value of one +<> to the equivalent value of an inferred or +specified <>. Casts between values of +<> will result in data loss when the value of +the type converted from is larger than the equivalent value of the type +converted to can accommodate. Casts between values of integral types and values +of floating point types will result in precision loss when the value of the +integral type converted from is unable to accurately represent the equivalent +value of the floating point type converted to and vice versa. -IMPORTANT: Explicit casts between numeric types can result in some data loss. A -smaller numeric type cannot necessarily accommodate the value from a larger -numeric type. You might also lose precision when casting from integer types -to floating point types. +The table below illustrates legal casts between values of +<> and if the cast must be explicit. Each cast +is read as a conversion of row to column. |==== -| | byte | short | char | int | long | float | double -| byte | | implicit | implicit | implicit | implicit | implicit | implicit -| short | explicit | | explicit | implicit | implicit | implicit | implicit -| char | explicit | explicit | | implicit | implicit | implicit | implicit -| int | explicit | explicit | explicit | | implicit | implicit | implicit -| long | explicit | explicit | explicit | explicit | | implicit | implicit -| float | explicit | explicit | explicit | explicit | explicit | | implicit +| | byte | short | char | int | long | float | double +| byte | | implicit | implicit | implicit | implicit | implicit | implicit +| short | explicit | | explicit | implicit | implicit | implicit | implicit +| char | explicit | explicit | | implicit | implicit | implicit | implicit +| int | explicit | explicit | explicit | | implicit | implicit | implicit +| long | explicit | explicit | explicit | explicit | | implicit | implicit +| float | explicit | explicit | explicit | explicit | explicit | | implicit | double | explicit | explicit | explicit | explicit | explicit | explicit | |==== +*Examples* -Example(s) -[source,Java] +* Valid numeric casts. ++ +[source,Painless] +---- +<1> int a = 1; +<2> long b = a; +<3> short c = (short)b; +<4> double e = (double)a; +---- ++ +<1> declare `int a`; + assign `1` to `a` +<2> declare `long b`; + implicit cast `long b` to `int`; + assign `int` value to `b` +<3> declare `short c`; + explicit cast `long b` to `short`; + assign `short` value to `c` +<4> declare `double e`; + explicit cast `int a` to `double`; + assign `double` value to `e`; + note this cast is extraneous and can be implicit ++ +* Invalid numeric casts resulting in errors. ++ +[source,Painless] ---- -int a = 1; // Declare int variable a and set it to the literal - // value 1 -long b = a; // Declare long variable b and set it to int variable - // a with an implicit cast to convert from int to long -short c = (short)b; // Declare short variable c, explicitly cast b to a - // short, and assign b to c -byte d = a; // ERROR: Casting an int to a byte requires an explicit - // cast -double e = (double)a; // Explicitly cast int variable a to a double and assign - // it to the double variable e. The explicit cast is - // allowed, but it is not necessary. +<1> int a = 1.0; +<2> int b = 2; +<3> byte c = b; ---- ++ +<1> declare `int i`; + *error*: cannot implicitly cast `double 1.0` to `int` +<2> declare `int b`; + assign `int 2` to `b`; [[reference-casting]] ==== Reference Casting diff --git a/docs/painless/painless-types.asciidoc b/docs/painless/painless-types.asciidoc index c936d903ffdf1..465c53ac1d931 100644 --- a/docs/painless/painless-types.asciidoc +++ b/docs/painless/painless-types.asciidoc @@ -17,7 +17,7 @@ and are allocated to non-heap memory. Primitive type values are copied when function as arguments. Primitive types have corresponding <> (also -known as a <>). Any member of the corresponding +known as <>). Any member of the corresponding <> can be <> or <> by executing the appropriate operation on the primitive type value. Operations performed in this manner convert @@ -86,11 +86,11 @@ logical quantity with two possible values of `true` and `false` ---- + <1> declare `int i`; - assign `1` to `i` + assign `int 1` to `i` <2> declare `double d`; - assign the default value of `0.0` to `d` + assign the default value `double 0.0` to `d` <3> declare `boolean b`; - assign `true` to `b` + assign `boolean true` to `b` + * Method call on a primitive type from the corresponding <>. @@ -102,9 +102,9 @@ logical quantity with two possible values of `true` and `false` ---- + <1> declare `int i`; - assign `1` to `i` -<2> implicitly convert (box) `i` to the reference type `Integer`; - call the non-static member method `toString` on the converted (boxed) value + assign `int 1` to `i` +<2> box `i` to `Integer`; + return `String '1'` from call `toString` [[reference-types]] ==== Reference Types @@ -187,12 +187,14 @@ relationships. ---- + <1> declare `List l`; - assign a new `ArrayList` to `l` -<2> call non-static member method `add` on `l` with arguments of `1` + implicit cast `new Arraylist` to `List`; + assign to `l` +<2> call `add` on `l` with arguments `(box int 1)` <3> declare `int i`; - call non-static member method `get` on `l` with arguments `0`; - add `1` to `2`; - assign `3` to `i` + return `Integer 1` from call `get` on `l` with arguments `(int 0)`; + unbox Integer `1`; + add `int 1` and `int 2`; + assign to `i` + * Sharing a reference type instance. + @@ -206,16 +208,19 @@ relationships. ---- + <1> declare `List l0`; - assign a new `ArrayList` to `l0` + implicit cast `new ArrayList` to `List`; + assign to `l0` <2> declare `List l1`; - assign a shallow-copy of `l0` to `l1` -<3> call non-static member method `add` on l0 with arguments of `1` -<4> call non-static member method `add` on l1 with arguments of `2` + assign shallow-copy of `l0` to `l1` +<3> call `add` on `l0` with arguments `(box int 1)` +<4> call `add` on `l1` with arguments `(box int 2)` <5> note `l0` and `l1` refer to the same reference type instance; - call non-static member method `get` on `l1` with arguments `0`; - call non-static member method `get` on `l0` with arguments `1`; - add `1` to `2`; - assign `3` to `i`; + return `Integer 1` from call `get` on `l1` with arguments `(int 0)`; + unbox `Integer 1`; + return `Integer 2` from call get` on `l0` with arguments `(int 1)`; + unbox `Integer 2`; + add `int 1` and `int 2`; + assign to `i`; + * Using the static members of a reference type. + diff --git a/docs/painless/painless-variables.asciidoc b/docs/painless/painless-variables.asciidoc index 08d4f58a82323..719f088f3a487 100644 --- a/docs/painless/painless-variables.asciidoc +++ b/docs/painless/painless-variables.asciidoc @@ -44,14 +44,22 @@ assignment: '=' expression; <7> Map[][] m; ---- + -<1> declare a variable of type `int` and identifier `x` -<2> declare a variable of type `List` and identifier `y` -<3> declare three variables of type `int` and identifiers `x`, `y`, `z` -<4> declare a variable of type `def` and identifier `d` -<5> declare a variable of type `int` and identifier `i`; - assign the integer literal `10` to `i` -<6> declare a 1-dimensional array type variable of `float` and identifier `f` -<7> declare a 2-dimensional array type variable of `Map` and identifier `m` +<1> declare `int x`; + assign default value `null` to `x` +<2> declare `List y`; + assign default value `null` to `y` +<3> declare `int x`, `int y`, and int `z`; + assign default value `int 0` to `x`; + assign default value `int 0` to `y`; + assign default value `int 0` to `z`; +<4> declare `def d`; + assign default value `null` to `d` +<5> declare `int i`; + assign `int 10` to `i` +<6> declare `float[] f`; + assign default value `null` to `f` +<7> declare `Map[][] m`; + assign default value `null` to `m` [[assignment]] ==== Assignment @@ -60,7 +68,7 @@ Use the `equals` operator (`=`) to assign a value to a variable. Any expression that produces a value can be assigned to any variable as long as the <> are the same or the resultant <> can be implicitly <> to -the variable <>. Otherwise, an error will occur. +the variable <>. *Grammar* [source,ANTLR4] @@ -79,8 +87,8 @@ assignment: ID '=' expression ---- + <1> declare `int i`; - assign default value `0` to `i` -<2> assign `10` to `i` + assign default value `int 0` to `i` +<2> assign `int 10` to `i` + * <> combined with immediate variable assignment. + @@ -91,9 +99,9 @@ assignment: ID '=' expression ---- + <1> declare `int i`; - assign `10` to `i` + assign `int 10` to `i` <2> declare `double j`; - assign `2.0` to `j` + assign `double 2.0` to `j` + * Assignment of one variable to another using <>. @@ -105,7 +113,7 @@ assignment: ID '=' expression ---- + <1> declare `int i`; - assign `10` to `i` + assign `int 10` to `i` <2> declare `int j`; assign `j` to `i` + @@ -119,9 +127,10 @@ assignment: ID '=' expression ---- + <1> declare `ArrayList l`; - assign a newly-allocated `Arraylist` to `l` + assign `new Arraylist` to `l` <2> declare `Map m`; - assign a newly-allocated `HashMap` to `m` with an implicit cast to `Map` + implicit cast `new HashMap` to `Map`; + assign to `m` + * Assignment of one variable to another using <>. @@ -135,12 +144,13 @@ assignment: ID '=' expression ---- + <1> declare `List l`; - assign a newly-allocated `Arraylist` to `l` with an implicit cast to `List` + implicit cast `new ArrayList` to `List`; + assign to `l` <2> declare `List k`; - assign a shallow-copy of `l` to `k` + assign shallow-copy of `l` to `k`; <3> declare `List m`; assign default value `null` to `m` -<4> assign a shallow-copy of `k` to `m` +<4> assign shallow-copy of `k` to `m` + * Assignment with the <> using the <>. @@ -152,16 +162,17 @@ assignment: ID '=' expression <3> ia1[0] = 1; <4> int[] ib1 = ia1; <5> int[][] ic2 = new int[2][5]; -<6> ic2[0][0] = 2; +<6> ic2[1][3] = 2; <7> ic2[0] = ia1; ---- + -<1> declare `int[] ia1` -<2> assign a newly-allocated 1-dimensional array type of `int` to `ia1` -<3> assign `1` to the 0th index of `ia1` +<1> declare `int[] ia1`; + assign default value `null` to `ia1` +<2> assign `new 1-d int array` to `ia1` with length `[2]` +<3> assign `int 1` to index `[0]` of `ia1` <4> declare `int[] ib1`; - assign a shallow-copy of `ia1` to `ib1` + assign shallow-copy of `ia1` to `ib1` <5> declare `int[][] ic2`; - assign a newly-allocated 2-dimensional array type of `int` to `ic2` -<6> assign `2` to the 0th index of the 0th index of `ic2` -<7> assign a shallow-copy of `ia1` to the 0th index of `ic2` \ No newline at end of file + assign `new 2-d int array` to `ic2` with length `[2, 5]` +<6> assign `int 2` to index `[1, 3]` of `ic2` +<7> assign shallow-copy of `ia1` to index `[0]` of `ic2`; \ No newline at end of file From 00ba531061b0d6cc1019d1f4eb02f5f51543579d Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Fri, 4 May 2018 15:58:05 -0700 Subject: [PATCH 12/27] Updated examples. --- docs/painless/painless-casting.asciidoc | 13 ++- docs/painless/painless-literals.asciidoc | 25 ++---- docs/painless/painless-types.asciidoc | 105 ++++++++++++---------- docs/painless/painless-variables.asciidoc | 77 +++++++++------- 4 files changed, 124 insertions(+), 96 deletions(-) diff --git a/docs/painless/painless-casting.asciidoc b/docs/painless/painless-casting.asciidoc index e7b90e94c1884..5ae4fb9c45630 100644 --- a/docs/painless/painless-casting.asciidoc +++ b/docs/painless/painless-casting.asciidoc @@ -105,6 +105,7 @@ is read as a conversion of row to column. *error*: cannot implicitly cast `double 1.0` to `int` <2> declare `int b`; assign `int 2` to `b`; +<3> exist [[reference-casting]] ==== Reference Casting @@ -159,6 +160,16 @@ int c = (int)x; // Declare int variable c, explicitly cast def variable x to an // int, and assign x to c ---- +[[character-string-casting]] +==== Character-String Casting +* Casting a <> value into a <> value. ++ +[source,Painless] +---- +String s = "s"; +char c = (char)s; +---- + [[boxing-unboxing]] ==== Boxing and Unboxing @@ -214,4 +225,4 @@ def x = 1; // Declare def variable x and set it to the literal int 1 through x + 2.0F // Add def variable x and the literal float 2.0. // At compile-time the types are promoted to def. // At run-time the types are promoted to float. ----- +---- \ No newline at end of file diff --git a/docs/painless/painless-literals.asciidoc b/docs/painless/painless-literals.asciidoc index 441cb264f1e15..9e536255e5f0a 100644 --- a/docs/painless/painless-literals.asciidoc +++ b/docs/painless/painless-literals.asciidoc @@ -49,8 +49,8 @@ HEX: '-'? '0' [xX] [0-9a-fA-F]+ [lL]?; Use floating point literals to specify a floating point value of the <> `float` or `double`. Use the following single letter designations to specify the <>: -`f` or `F` for `float` and `d` or `D` for `double`. If not specified, the type defaults -to `double`. +`f` or `F` for `float` and `d` or `D` for `double`. If not specified, the type +defaults to `double`. *Grammar* [source,ANTLR4] @@ -117,26 +117,19 @@ STRING: ( '"' ( '\\"' | '\\\\' | ~[\\"] )*? '"' ) [[characters]] ==== Characters -Use the <> to convert string literals or -<> values into <> values. -<> values converted into -<> values must be exactly one character in length -or an error will occur. +Character literals cannot be specified directly. Instead, use the +<> to convert <> +values into <> values. <> values +converted into <> values must be exactly one character +in length or an error will occur. *Examples* -* Casting string literals into <> values. +* <> string literals into +<> values. + [source,Painless] ---- (char)"C" (char)'c' ---- -+ -* Casting a <> value into a <> value. -+ -[source,Painless] ----- -String s = "s"; -char c = (char)s; ----- diff --git a/docs/painless/painless-types.asciidoc b/docs/painless/painless-types.asciidoc index 465c53ac1d931..d880b0696fc49 100644 --- a/docs/painless/painless-types.asciidoc +++ b/docs/painless/painless-types.asciidoc @@ -86,11 +86,11 @@ logical quantity with two possible values of `true` and `false` ---- + <1> declare `int i`; - assign `int 1` to `i` + assign value of `int 1` to `i` <2> declare `double d`; - assign the default value `double 0.0` to `d` + assign default value of `double 0.0` to `d` <3> declare `boolean b`; - assign `boolean true` to `b` + assign value of `boolean true` to `b` + * Method call on a primitive type from the corresponding <>. @@ -102,9 +102,9 @@ logical quantity with two possible values of `true` and `false` ---- + <1> declare `int i`; - assign `int 1` to `i` -<2> box `i` to `Integer`; - return `String '1'` from call `toString` + assign value of `int 1` to `i` +<2> box value of `i` -> `Integer 1`; + call `toString` on `Integer 1` -> `String '1'` [[reference-types]] ==== Reference Types @@ -116,7 +116,7 @@ use in scripts. A reference type instance is a single set of data for one reference type object allocated to the heap. A reference type instance is allocated using the -<>. +<>. Reference type values refer to reference type instances, and multiple reference type values may refer to a single reference type instance. A change to a @@ -177,7 +177,7 @@ relationships. *Examples* -* Reference types used in several different <>. +* Reference types used in several different <>. + [source,Painless] ---- @@ -187,14 +187,16 @@ relationships. ---- + <1> declare `List l`; - implicit cast `new Arraylist` to `List`; - assign to `l` -<2> call `add` on `l` with arguments `(box int 1)` + allocate `ArrayList` instance -> `ArrayList`; + implicit cast value of `Arraylist` to `List` -> `List`; + assign value of `List` to `l` +<2> box value of `int 1` -> `Integer 1`; + call `add` on `l` with arguments `(Integer 1)` <3> declare `int i`; - return `Integer 1` from call `get` on `l` with arguments `(int 0)`; - unbox Integer `1`; - add `int 1` and `int 2`; - assign to `i` + call `get` on `l` with arguments `(int 0)` -> `Integer 1`; + unbox value of Integer `1` -> `int 1`; + add value of `int 1` and value of `int 2` -> `int 3`; + assign value of `int 3` to `i` + * Sharing a reference type instance. + @@ -208,31 +210,37 @@ relationships. ---- + <1> declare `List l0`; - implicit cast `new ArrayList` to `List`; - assign to `l0` + allocate `ArrayList` instance -> `ArrayList`; + implicit cast value of `ArrayList` to `List` -> `List`; + assign value of `List` to `l0` <2> declare `List l1`; - assign shallow-copy of `l0` to `l1` -<3> call `add` on `l0` with arguments `(box int 1)` -<4> call `add` on `l1` with arguments `(box int 2)` -<5> note `l0` and `l1` refer to the same reference type instance; - return `Integer 1` from call `get` on `l1` with arguments `(int 0)`; - unbox `Integer 1`; - return `Integer 2` from call get` on `l0` with arguments `(int 1)`; - unbox `Integer 2`; - add `int 1` and `int 2`; - assign to `i`; + assign shallow-copy of value of `l0` to `l1` + (note `l0` and `l1` refer to the same instance) +<3> box value of `int 1` -> `Integer 1`; + call `add` on `l0` with arguments `(Integer 1)` +<4> box value of `int 2` -> `Integer 2`; + call `add` on `l1` with arguments `(Integer 2)` +<5> call `get` on `l1` with arguments `(int 0)` -> `Integer 1`; + unbox value of `Integer 1` -> `int 1`; + call get` on `l0` with arguments `(int 1)` -> `Integer 2`; + unbox value of `Integer 2` -> `int 2`; + add `int 1` and `int 2` -> `int 3`; + assign value of `int 3` to `i`; + * Using the static members of a reference type. + [source,Painless] ---- -<1> Integer.MAX_VALUE -<2> Long.parseLong("123L") +<1> int i = Integer.MAX_VALUE; +<2> Long l = Long.parseLong("123L"); ---- + -<1> access static field `MAX_VALUE` on reference type `Integer` -<2> call static member method `parseLong` on reference type `Long` with - arguments `long 123` +<1> declare `int i`; + access `MAX_VALUE` on `Integer` -> `int 2147483647`; + assign value of `int 2147483647` to `i` +<2> declare `Long l`; + call `parseLong` on `Long` with arguments `(long 123)` -> `Long 123`; + assign shallow-copy of value of `Long 123` to `l` [[dynamic-types]] ==== Dynamic Types @@ -262,17 +270,18 @@ reference types directly when performance is critical. + [source,Painless] ---- -<1> def i = 1; -<2> def l = new ArrayList(); -<3> l = i; +<1> def dp = 1; +<2> def dr = new ArrayList(); +<3> dr = dp; ---- + -<1> declare `def i`; - assign `1` to `i` -<2> declare `def l`; - assign a new `ArrayList` to `l` -<3> assign `i` to `l`; - note the switch in type from `ArrayList` to `int` +<1> declare `def dp`; + assign value of `int 1` to `dp` +<2> declare `def dr`; + allocate `ArrayList` instance -> `ArrayList`; + assign value of `ArrayList` to `dr` +<3> assign value of `dp` to `dr`; + (note the switch in type of `dr` from `ArrayList` to `int`) [[string-type]] ==== String Type @@ -296,13 +305,15 @@ While not required, the <> can allocate ---- + <1> declare `String r`; - assign `"some text"` to `r` + assign value of `"some text"` to `r` <2> declare `String s`; - assign `'some text'` to `s` + assign value of `'some text'` to `s` <3> declare `String t`; - assign new `String` with arguments `"some text"` to `t` + allocate `String` instance with arguments `("some text")` + -> `String "some text"`; + assign value of `String "some text"` to `t` <4> declare `String u`; - assign the default value of `null` to `u` + assign default value of `null` to `u` [[void-type]] ==== void Type @@ -361,8 +372,10 @@ the array type `int[][]`. <5> z[0] = y[9]; ---- + -<1> declare `int[] x` +<1> declare `int[] x`; + assign default value of `null` to `x` <2> declare `float[] y`; + assign a newly-allocated array type of `float` to `y` <3> declare `def z`; assign a newly-allocated array type of `float` to `z` diff --git a/docs/painless/painless-variables.asciidoc b/docs/painless/painless-variables.asciidoc index 719f088f3a487..5bc3f318a1f5f 100644 --- a/docs/painless/painless-variables.asciidoc +++ b/docs/painless/painless-variables.asciidoc @@ -37,7 +37,7 @@ assignment: '=' expression; ---- <1> int x; <2> List y; -<3> int x, y, z; +<3> int x, y = 5, z; <4> def d; <5> int i = 10; <6> float[] f; @@ -45,26 +45,28 @@ assignment: '=' expression; ---- + <1> declare `int x`; - assign default value `null` to `x` + assign default value of `null` to `x` <2> declare `List y`; - assign default value `null` to `y` -<3> declare `int x`, `int y`, and int `z`; - assign default value `int 0` to `x`; - assign default value `int 0` to `y`; - assign default value `int 0` to `z`; + assign default value of `null` to `y` +<3> declare `int x`; + assign default value of `int 0` to `x`; + declare `int y`; + assign value of `int 5` to `y`; + declare `int z`; + assign default value of `int 0` to `z`; <4> declare `def d`; - assign default value `null` to `d` + assign default value of `null` to `d` <5> declare `int i`; - assign `int 10` to `i` + assign value of `int 10` to `i` <6> declare `float[] f`; - assign default value `null` to `f` + assign default value of `null` to `f` <7> declare `Map[][] m`; - assign default value `null` to `m` + assign default value of `null` to `m` [[assignment]] ==== Assignment -Use the `equals` operator (`=`) to assign a value to a variable. Any expression +Use the `equals operator '='` to assign a value to a variable. Any expression that produces a value can be assigned to any variable as long as the <> are the same or the resultant <> can be implicitly <> to @@ -87,8 +89,8 @@ assignment: ID '=' expression ---- + <1> declare `int i`; - assign default value `int 0` to `i` -<2> assign `int 10` to `i` + assign default value of `int 0` to `i` +<2> assign value of `int 10` to `i` + * <> combined with immediate variable assignment. + @@ -99,9 +101,9 @@ assignment: ID '=' expression ---- + <1> declare `int i`; - assign `int 10` to `i` + assign value of `int 10` to `i` <2> declare `double j`; - assign `double 2.0` to `j` + assign value of `double 2.0` to `j` + * Assignment of one variable to another using <>. @@ -113,9 +115,9 @@ assignment: ID '=' expression ---- + <1> declare `int i`; - assign `int 10` to `i` + assign value of `int 10` to `i` <2> declare `int j`; - assign `j` to `i` + assign value of `j` to `i` + * Assignment with <> using the <>. @@ -127,10 +129,12 @@ assignment: ID '=' expression ---- + <1> declare `ArrayList l`; - assign `new Arraylist` to `l` + allocate `ArrayList` instance -> `ArrayList`; + assign value of `ArrayList` to `l` <2> declare `Map m`; - implicit cast `new HashMap` to `Map`; - assign to `m` + allocate `HashMap` instance -> `HashMap`; + implicit cast value of `HashMap` to `Map` -> `Map`; + assign value of `Map` to `m` + * Assignment of one variable to another using <>. @@ -144,13 +148,16 @@ assignment: ID '=' expression ---- + <1> declare `List l`; - implicit cast `new ArrayList` to `List`; - assign to `l` + allocate `ArrayList` instance -> `ArrayList`; + implicit cast value of `ArrayList` to `List` -> `List`; + assign value of `List` to `l` <2> declare `List k`; - assign shallow-copy of `l` to `k`; + assign shallow-copy of value of `l` to `k`; + (note `l` and `k` refer to the same instance) <3> declare `List m`; - assign default value `null` to `m` -<4> assign shallow-copy of `k` to `m` + assign default value of `null` to `m` +<4> assign shallow-copy of value of `k` to `m`; + (note `l`, `k`, and `m` refer to the same instance) + * Assignment with the <> using the <>. @@ -167,12 +174,16 @@ assignment: ID '=' expression ---- + <1> declare `int[] ia1`; - assign default value `null` to `ia1` -<2> assign `new 1-d int array` to `ia1` with length `[2]` -<3> assign `int 1` to index `[0]` of `ia1` + assign default value of `null` to `ia1` +<2> allocate `1-d int array` instance with `length [2]` -> `1-d int array`; + assign value of `1-d int array` to `ia1` +<3> assign value of `int 1` to `index [0]` of `ia1` <4> declare `int[] ib1`; - assign shallow-copy of `ia1` to `ib1` + assign shallow-copy of value of `ia1` to `ib1`; + (note `ia1` and `ib1` refer to the same instance) <5> declare `int[][] ic2`; - assign `new 2-d int array` to `ic2` with length `[2, 5]` -<6> assign `int 2` to index `[1, 3]` of `ic2` -<7> assign shallow-copy of `ia1` to index `[0]` of `ic2`; \ No newline at end of file + allocate `2-d int array` instance with `length [2, 5]` -> `2-d int array`; + assign value of `2-d int array` to `ic2` +<6> assign value of `int 2` to `index [1, 3]` of `ic2` +<7> assign shallow-copy of value of `ia1` to `index [0]` of `ic2`; + (note `ia1`, `ib1`, and `index [0]` of `ia2` refer to the same instance) From 7bcd114ba3cc7bcf760badc0c150e37276682874 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Mon, 7 May 2018 09:15:48 -0700 Subject: [PATCH 13/27] More changes. --- docs/painless/painless-types.asciidoc | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/painless/painless-types.asciidoc b/docs/painless/painless-types.asciidoc index d880b0696fc49..7fe08ae902ebd 100644 --- a/docs/painless/painless-types.asciidoc +++ b/docs/painless/painless-types.asciidoc @@ -375,12 +375,14 @@ the array type `int[][]`. <1> declare `int[] x`; assign default value of `null` to `x` <2> declare `float[] y`; - - assign a newly-allocated array type of `float` to `y` + allocate `1-d float array` instance with `length [10]` + -> `1-d float array`; + assign value of `1-d float array` to `y` <3> declare `def z`; - assign a newly-allocated array type of `float` to `z` -<4> assign `1.0F` to the 9th index of `y` -<5> assign the value of 9th index of `y` to the 0th index of `z` + allocate `1-d float array` instance with `length [5]` -> `1-d float array`; + assign value of `1-d float array` to `z` +<4> assign value of `float 1.0` to `index [9]` of `y` +<5> assign value of `index [9]` of `y` to `index [0]` of `z` + * Use of a multi-dimensional array. + @@ -392,7 +394,9 @@ the array type `int[][]`. ---- + <1> declare `int[][][] ia`; - assign a newly-allocated 3-dimensional array type of `int` to `ia3` -<2> assign `99` to the 3rd index of the 2nd index of the 1st index of `ia3` -<3> assign the value of the 3rd index of the 2nd index of the 1st index - of `ia3` to `i` \ No newline at end of file + allocate `3-d int array` instance with length `[2, 3, 4]` + -> `3-d float array`; + assign value of `3-d float array` to `ia3` +<2> assign value of `int 99` to `index [1, 2, 3]` of `ia3` +<3> declare `int i`; + assign value of `index [1, 2, 3]` of `ia3` to `i` \ No newline at end of file From 68059aee13396c761e7958d2ac6fd4d2c87e28c0 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Wed, 9 May 2018 15:22:15 -0700 Subject: [PATCH 14/27] More example clean up. --- docs/painless/painless-casting.asciidoc | 47 ++++++----- docs/painless/painless-literals.asciidoc | 5 +- docs/painless/painless-types.asciidoc | 99 +++++++++++++---------- docs/painless/painless-variables.asciidoc | 47 ++++++----- 4 files changed, 115 insertions(+), 83 deletions(-) diff --git a/docs/painless/painless-casting.asciidoc b/docs/painless/painless-casting.asciidoc index 5ae4fb9c45630..11cf4eb89bd97 100644 --- a/docs/painless/painless-casting.asciidoc +++ b/docs/painless/painless-casting.asciidoc @@ -30,14 +30,18 @@ cast: '(' TYPE ')' expression ---- + <1> declare `int i`; - explicitly cast `long 5` to `int`; - assign `5` to `i` + explicit cast value of `long 5` to value of `int 5` -> `int 5`; + assign `int 5` to `i` <2> declare `Map m`; - implicit cast new `HashMap` to `Map`; - assign `Map` value to `m` + allocate `HashMap` instance -> `HashMap reference`; + implicit cast value of `HashMap reference` to value of `Map reference` + -> `Map reference`; + assign value of `Map reference` to `m` <3> declare `HashMap hm`; - explicit cast `Map m` to `HashMap`; - assign `Map` value to `hm` + access `m` -> `Map reference`; + explicit cast value of `Map reference` to value of `HashMap reference` + -> `HashMap reference`; + assign value of `HashMap reference` to `hm` [[numeric-casting]] ==== Numeric Casting @@ -80,32 +84,37 @@ is read as a conversion of row to column. ---- + <1> declare `int a`; - assign `1` to `a` + assign `int 1` to `a` <2> declare `long b`; - implicit cast `long b` to `int`; - assign `int` value to `b` + access `a` -> `int 1`; + implicit cast value of `int 1` to value of `long 1` -> `long 1`; + assign value of `long 1` to `b` <3> declare `short c`; - explicit cast `long b` to `short`; - assign `short` value to `c` + access `b` -> `long 1`; + explicit cast value of `long 1` to value of `short 1` -> `short 1`; + assign `short 1` value to `c` <4> declare `double e`; - explicit cast `int a` to `double`; - assign `double` value to `e`; - note this cast is extraneous and can be implicit + access `a` -> `int 1`; + explicit cast value of `int 1` to `double 1.0`; + assign value of `double 1.0` to `e`; + (note this cast is extraneous and can be implicit) + * Invalid numeric casts resulting in errors. + [source,Painless] ---- -<1> int a = 1.0; +<1> int a = 1.0; // error <2> int b = 2; -<3> byte c = b; +<3> byte c = b; // error ---- + <1> declare `int i`; - *error*: cannot implicitly cast `double 1.0` to `int` + *error* -> cannot implicit cast value of `double 1.0` to `int 1` <2> declare `int b`; - assign `int 2` to `b`; -<3> exist + assign `int 2` to `b` +<3> declare byte `c`; + access `b` -> `int 2`; + *error* -> cannot implicit cast value of `int 2` to `byte 2` [[reference-casting]] ==== Reference Casting diff --git a/docs/painless/painless-literals.asciidoc b/docs/painless/painless-literals.asciidoc index 9e536255e5f0a..e408365f805c1 100644 --- a/docs/painless/painless-literals.asciidoc +++ b/docs/painless/painless-literals.asciidoc @@ -119,9 +119,8 @@ STRING: ( '"' ( '\\"' | '\\\\' | ~[\\"] )*? '"' ) Character literals cannot be specified directly. Instead, use the <> to convert <> -values into <> values. <> values -converted into <> values must be exactly one character -in length or an error will occur. +values into <> values. Use only <> +values one character in length for this conversion or an error will occur. *Examples* diff --git a/docs/painless/painless-types.asciidoc b/docs/painless/painless-types.asciidoc index 7fe08ae902ebd..6dce1f86fdbf3 100644 --- a/docs/painless/painless-types.asciidoc +++ b/docs/painless/painless-types.asciidoc @@ -103,8 +103,9 @@ logical quantity with two possible values of `true` and `false` + <1> declare `int i`; assign value of `int 1` to `i` -<2> box value of `i` -> `Integer 1`; - call `toString` on `Integer 1` -> `String '1'` +<2> access `i` -> `int 1`; + box value of `int 1` -> `Integer 1 reference`; + call `toString` on `Integer 1 reference` -> `String '1'` [[reference-types]] ==== Reference Types @@ -187,14 +188,17 @@ relationships. ---- + <1> declare `List l`; - allocate `ArrayList` instance -> `ArrayList`; - implicit cast value of `Arraylist` to `List` -> `List`; - assign value of `List` to `l` -<2> box value of `int 1` -> `Integer 1`; - call `add` on `l` with arguments `(Integer 1)` + allocate `ArrayList` instance -> `ArrayList reference`; + implicit cast value of `Arraylist reference` to value of `List reference` + -> `List reference`; + assign value of `List reference` to `l` +<2> access `l` -> `List reference`; + implicit cast value of `int 1` to value of `def` -> `def` + call `add` on `List reference` with arguments (`def`) <3> declare `int i`; - call `get` on `l` with arguments `(int 0)` -> `Integer 1`; - unbox value of Integer `1` -> `int 1`; + access `l` -> `List reference`; + call `get` on `List reference` with arguments (`int 0`) -> `def`; + implicit cast value of `def` to value of `int 1` -> `int 1`; add value of `int 1` and value of `int 2` -> `int 3`; assign value of `int 3` to `i` + @@ -210,21 +214,28 @@ relationships. ---- + <1> declare `List l0`; - allocate `ArrayList` instance -> `ArrayList`; - implicit cast value of `ArrayList` to `List` -> `List`; - assign value of `List` to `l0` + allocate `ArrayList` instance -> `ArrayList reference`; + implicit cast value of `ArrayList reference` to value of `List reference` + -> `List reference`; + assign value of `List reference` to `l0` <2> declare `List l1`; - assign shallow-copy of value of `l0` to `l1` - (note `l0` and `l1` refer to the same instance) -<3> box value of `int 1` -> `Integer 1`; - call `add` on `l0` with arguments `(Integer 1)` -<4> box value of `int 2` -> `Integer 2`; - call `add` on `l1` with arguments `(Integer 2)` -<5> call `get` on `l1` with arguments `(int 0)` -> `Integer 1`; - unbox value of `Integer 1` -> `int 1`; - call get` on `l0` with arguments `(int 1)` -> `Integer 2`; - unbox value of `Integer 2` -> `int 2`; - add `int 1` and `int 2` -> `int 3`; + access `l0` -> `List reference`; + assign value of `List reference` to `l1` + (note `l0` and `l1` refer to the same instance known as a shallow-copy) +<3> access `l0` -> `List reference`; + implicit cast value of `int 1` to value of `def` -> `def` + call `add` on `List reference` with arguments (`def`) +<4> access `l1` -> `List reference`; + implicit cast value of `int 2` to value of `def` -> `def` + call `add` on `List reference` with arguments (`def`) +<5> declare `int i`; + access `l0` -> `List reference`; + call `get` on `List reference` with arguments (`int 0`) -> `def @0`; + implicit cast value of `def @0` to value of `int 1` -> `int 1`; + access `l1` -> `List reference`; + call `get` on `List reference` with arguments (`int 1`) -> `def @1`; + implicit cast value of `def @1` to value of `int 2` -> `int 2`; + add value of `int 1` and value of `int 2` -> `int 3`; assign value of `int 3` to `i`; + * Using the static members of a reference type. @@ -232,15 +243,15 @@ relationships. [source,Painless] ---- <1> int i = Integer.MAX_VALUE; -<2> Long l = Long.parseLong("123L"); +<2> long l = Long.parseLong("123L"); ---- + <1> declare `int i`; access `MAX_VALUE` on `Integer` -> `int 2147483647`; assign value of `int 2147483647` to `i` -<2> declare `Long l`; - call `parseLong` on `Long` with arguments `(long 123)` -> `Long 123`; - assign shallow-copy of value of `Long 123` to `l` +<2> declare `long l`; + call `parseLong` on `Long` with arguments (`long 123`) -> `long 123`; + assign value of `long 123` to `l` [[dynamic-types]] ==== Dynamic Types @@ -278,9 +289,10 @@ reference types directly when performance is critical. <1> declare `def dp`; assign value of `int 1` to `dp` <2> declare `def dr`; - allocate `ArrayList` instance -> `ArrayList`; - assign value of `ArrayList` to `dr` -<3> assign value of `dp` to `dr`; + allocate `ArrayList` instance -> `ArrayList reference`; + assign value of `ArrayList reference` to `dr` +<3> access `dp` -> `int 1`; + assign value of `int 1` to `dr`; (note the switch in type of `dr` from `ArrayList` to `int`) [[string-type]] @@ -305,12 +317,12 @@ While not required, the <> can allocate ---- + <1> declare `String r`; - assign value of `"some text"` to `r` + assign value of `String "some text"` to `r` <2> declare `String s`; - assign value of `'some text'` to `s` + assign value of `String 'some text'` to `s` <3> declare `String t`; - allocate `String` instance with arguments `("some text")` - -> `String "some text"`; + allocate `String` instance with arguments (`String "some text"`) + -> `String "some text"`; assign value of `String "some text"` to `t` <4> declare `String u`; assign default value of `null` to `u` @@ -376,13 +388,15 @@ the array type `int[][]`. assign default value of `null` to `x` <2> declare `float[] y`; allocate `1-d float array` instance with `length [10]` - -> `1-d float array`; - assign value of `1-d float array` to `y` + -> `1-d float array reference`; + assign value of `1-d float array reference` to `y` <3> declare `def z`; - allocate `1-d float array` instance with `length [5]` -> `1-d float array`; - assign value of `1-d float array` to `z` + allocate `1-d float array` instance with `length [5]` + -> `1-d float array reference`; + assign value of `1-d float array reference` to `z` <4> assign value of `float 1.0` to `index [9]` of `y` -<5> assign value of `index [9]` of `y` to `index [0]` of `z` +<5> access `index [9]` of `y` -> `float 1.0`; + assign `float 1.0` to `index [0]` of `z` + * Use of a multi-dimensional array. + @@ -395,8 +409,9 @@ the array type `int[][]`. + <1> declare `int[][][] ia`; allocate `3-d int array` instance with length `[2, 3, 4]` - -> `3-d float array`; - assign value of `3-d float array` to `ia3` + -> `3-d float array reference`; + assign value of `3-d float array reference` to `ia3` <2> assign value of `int 99` to `index [1, 2, 3]` of `ia3` <3> declare `int i`; - assign value of `index [1, 2, 3]` of `ia3` to `i` \ No newline at end of file + access `index [1, 2, 3]` of `ia3` -> `int 99`; + assign value of `int 99` to `i` \ No newline at end of file diff --git a/docs/painless/painless-variables.asciidoc b/docs/painless/painless-variables.asciidoc index 5bc3f318a1f5f..922105386b0ab 100644 --- a/docs/painless/painless-variables.asciidoc +++ b/docs/painless/painless-variables.asciidoc @@ -117,7 +117,8 @@ assignment: ID '=' expression <1> declare `int i`; assign value of `int 10` to `i` <2> declare `int j`; - assign value of `j` to `i` + access `i` -> `int 10`; + assign value of `int 10` to `j` + * Assignment with <> using the <>. @@ -129,12 +130,13 @@ assignment: ID '=' expression ---- + <1> declare `ArrayList l`; - allocate `ArrayList` instance -> `ArrayList`; - assign value of `ArrayList` to `l` + allocate `ArrayList` instance -> `ArrayList reference`; + assign value of `ArrayList reference` to `l` <2> declare `Map m`; - allocate `HashMap` instance -> `HashMap`; - implicit cast value of `HashMap` to `Map` -> `Map`; - assign value of `Map` to `m` + allocate `HashMap` instance -> `HashMap reference`; + implicit cast value of `HashMap reference` to value of `Map reference` + -> `Map reference`; + assign value of `Map reference` to `m` + * Assignment of one variable to another using <>. @@ -148,15 +150,18 @@ assignment: ID '=' expression ---- + <1> declare `List l`; - allocate `ArrayList` instance -> `ArrayList`; - implicit cast value of `ArrayList` to `List` -> `List`; - assign value of `List` to `l` + allocate `ArrayList` instance -> `ArrayList reference`; + implicit cast value of `ArrayList reference` to value of `List reference` + -> `List reference`; + assign value of `List reference` to `l` <2> declare `List k`; - assign shallow-copy of value of `l` to `k`; - (note `l` and `k` refer to the same instance) + access `l` -> `List reference`; + assign value of `List reference` to `k`; + (note `l` and `k` refer to the same instance known as a shallow-copy) <3> declare `List m`; assign default value of `null` to `m` -<4> assign shallow-copy of value of `k` to `m`; +<4> access `k` -> `List reference`; + assign value of `List reference` to `m`; (note `l`, `k`, and `m` refer to the same instance) + * Assignment with the <> using the @@ -175,15 +180,19 @@ assignment: ID '=' expression + <1> declare `int[] ia1`; assign default value of `null` to `ia1` -<2> allocate `1-d int array` instance with `length [2]` -> `1-d int array`; - assign value of `1-d int array` to `ia1` +<2> allocate `1-d int array` instance with `length [2]` + -> `1-d int array reference`; + assign value of `1-d int array reference` to `ia1` <3> assign value of `int 1` to `index [0]` of `ia1` <4> declare `int[] ib1`; - assign shallow-copy of value of `ia1` to `ib1`; - (note `ia1` and `ib1` refer to the same instance) + access `ia1` -> `1-d int array reference`; + assign value of `1-d int array reference` to `ib1`; + (note `ia1` and `ib1` refer to the same instance known as a shallow copy) <5> declare `int[][] ic2`; - allocate `2-d int array` instance with `length [2, 5]` -> `2-d int array`; - assign value of `2-d int array` to `ic2` + allocate `2-d int array` instance with `length [2, 5]` + -> `2-d int array reference`; + assign value of `2-d int array reference` to `ic2` <6> assign value of `int 2` to `index [1, 3]` of `ic2` -<7> assign shallow-copy of value of `ia1` to `index [0]` of `ic2`; +<7> access `ia1` -> `1-d int array reference`; + assign value of `1-d int array reference` to `index [0]` of `ic2`; (note `ia1`, `ib1`, and `index [0]` of `ia2` refer to the same instance) From 73a24f08c589975ec8a63f0ae94f48373ba1e035 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Wed, 9 May 2018 16:30:12 -0700 Subject: [PATCH 15/27] More casting clean up. --- docs/painless/painless-casting.asciidoc | 126 ++++++++++++++++-------- 1 file changed, 84 insertions(+), 42 deletions(-) diff --git a/docs/painless/painless-casting.asciidoc b/docs/painless/painless-casting.asciidoc index 11cf4eb89bd97..231de6a94eb81 100644 --- a/docs/painless/painless-casting.asciidoc +++ b/docs/painless/painless-casting.asciidoc @@ -43,18 +43,18 @@ cast: '(' TYPE ')' expression -> `HashMap reference`; assign value of `HashMap reference` to `hm` -[[numeric-casting]] -==== Numeric Casting +[[numeric-type-casting]] +==== Numeric Type Casting -A numeric cast is the conversion of the value of one +A numeric type cast is the conversion of the value of one <> to the equivalent value of an inferred or specified <>. Casts between values of -<> will result in data loss when the value of -the type converted from is larger than the equivalent value of the type -converted to can accommodate. Casts between values of integral types and values -of floating point types will result in precision loss when the value of the -integral type converted from is unable to accurately represent the equivalent -value of the floating point type converted to and vice versa. +numeric types will result in data loss when the value of the type converted from +is larger than the equivalent value of the type converted to can accommodate. +Casts between values of integral types and values of floating point types will +result in precision loss when the value of the integral type converted from is +unable to accurately represent the equivalent value of the floating point type +converted to and vice versa. The table below illustrates legal casts between values of <> and if the cast must be explicit. Each cast @@ -73,7 +73,7 @@ is read as a conversion of row to column. *Examples* -* Valid numeric casts. +* Valid numeric type casts. + [source,Painless] ---- @@ -97,9 +97,9 @@ is read as a conversion of row to column. access `a` -> `int 1`; explicit cast value of `int 1` to `double 1.0`; assign value of `double 1.0` to `e`; - (note this cast is extraneous and can be implicit) + (note the explicit cast is extraneous, and an implicit cast is valid) + -* Invalid numeric casts resulting in errors. +* Invalid numeric type casts resulting in errors. + [source,Painless] ---- @@ -109,44 +109,86 @@ is read as a conversion of row to column. ---- + <1> declare `int i`; - *error* -> cannot implicit cast value of `double 1.0` to `int 1` + *error* -> cannot implicit cast value of `double 1.0` to value of `int 1`; + (note an explicit cast is valid) <2> declare `int b`; assign `int 2` to `b` <3> declare byte `c`; access `b` -> `int 2`; - *error* -> cannot implicit cast value of `int 2` to `byte 2` + *error* -> cannot implicit cast value of `int 2` to value of `byte 2`; + (note an explicit cast is valid) -[[reference-casting]] -==== Reference Casting +[[reference-type-casting]] +==== Reference Type Casting -A reference type can be implicitly cast to another reference type as long as -the type being cast _from_ is a descendant of the type being cast _to_. A -reference type can be explicitly cast _to_ if the type being cast to is a -descendant of the type being cast _from_. +A reference type cast is the conversion of the value of one +<> to the equivalent value of an inferred or +specified <>. Implicit casts between +reference type values are allowed when the reference type being cast *from* +is a descendant of the reference type being cast *to*. Explicit casts between +reference type values are allowed when the reference type being cast *from* +is a descendant of the reference type being cast *to* or the reference type +being cast *to* is a descendant of the reference type being cast *from*. -*Examples:* -[source,Java] +*Examples* + +* Valid reference type casts. ++ +[source,Painless] ---- -List x; // Declare List variable x -ArrayList y = new ArrayList(); // Declare ArrayList variable y and assign it a - // newly allocated ArrayList [1] -x = y; // Assign Arraylist y to List x using an - // implicit cast -y = (ArrayList)x; // Explicitly cast List x to an ArrayList and - // assign it to ArrayList y -x = (List)y; // Set List x to ArrayList y using an explicit - // cast (the explicit cast is not necessary) -y = x; // ERROR: List x cannot be implicitly cast to - // an ArrayList, an explicit cast is required -Map m = y; // ERROR: Cannot implicitly or explicitly cast [2] - // an ArrayList to a Map, no relationship - // exists between the two types. ----- -[1] `ArrayList` is a descendant of the `List` type. -[2] `Map` is unrelated to the `List` and `ArrayList` types. - -[[def-type-casting]] -==== def Type Casting +<1> List x; +<2> ArrayList y = new ArrayList(); +<3> x = y; +<4> y = (ArrayList)x; +<5> x = (List)y; +---- ++ +<1> declare `List x`; + assign default value `null` to `x` +<2> declare `ArrayList y`; + allocate `ArrayList` instance -> `ArrayList reference`; + assign value of `ArrayList reference` to `y`; +<3> access `y` -> `ArrayList reference`; + implicit cast value of `ArrayList reference` to value of `List reference` + -> `List reference`; + assign `List reference` to `x`; + (note `ArrayList` is a descendant of `List`) +<4> access `x` -> `List reference`; + explicit cast value of `List reference` to value of `ArrayList reference` + -> `ArrayList reference`; + assign `ArrayList reference` to `y`; +<5> access `y` -> `ArrayList reference`; + explicit cast value of `ArrayList reference` to value of `List reference` + -> `List reference`; + assign `List reference` to `x`; + (note the explicit cast is extraneous, and an implicit cast is valid) ++ +* Invalid reference type casts resulting in errors. ++ +[source,Painless] +---- +<1> List x = new ArrayList(); +<2> ArrayList y = x; // error +<3> Map m = (Map)x; // error +---- ++ +<1> declare `List x`; + allocate `ArrayList` instance -> `ArrayList reference`; + implicit cast value of `ArrayList reference` to value of `List reference` + -> `List reference`; + assign `List reference` to `x` +<2> declare `ArrayList y`; + access `x` -> `List reference`; + *error* -> cannot implicit cast `List reference` to `ArrayList reference`; + (note an explicit is valid since `ArrayList` is a descendant of `List`) +<3> declare `ArrayList y`; + access `x` -> `List reference`; + *error* -> cannot explicit cast `List reference` to `Map reference`; + (note no cast would be valid since neither `List` nor `Map` is a descendant + of the other) + +[[dynamic-type-casting]] +==== Dynamic Type Casting All primitive and reference types can always be implicitly cast to `def`. While it is possible to explicitly cast to `def`, it is not necessary. From c3fcd67383762eab01d898b44d82adba565b83dc Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Wed, 9 May 2018 21:15:25 -0700 Subject: [PATCH 16/27] More clean up. --- docs/painless/painless-casting.asciidoc | 41 ++++++---- docs/painless/painless-types.asciidoc | 104 ++++++++++++++---------- 2 files changed, 84 insertions(+), 61 deletions(-) diff --git a/docs/painless/painless-casting.asciidoc b/docs/painless/painless-casting.asciidoc index 231de6a94eb81..9f6c95a37543d 100644 --- a/docs/painless/painless-casting.asciidoc +++ b/docs/painless/painless-casting.asciidoc @@ -46,19 +46,19 @@ cast: '(' TYPE ')' expression [[numeric-type-casting]] ==== Numeric Type Casting -A numeric type cast is the conversion of the value of one +A <> cast is the conversion of the value of one <> to the equivalent value of an inferred or specified <>. Casts between values of -numeric types will result in data loss when the value of the type converted from -is larger than the equivalent value of the type converted to can accommodate. -Casts between values of integral types and values of floating point types will -result in precision loss when the value of the integral type converted from is -unable to accurately represent the equivalent value of the floating point type -converted to and vice versa. +<> will result in data loss when the value of +the type converted from is larger than the equivalent value of the type +converted to can accommodate. Casts between values of integral types and values +of floating point types will result in precision loss when the value of the +integral type converted from is unable to accurately represent the equivalent +value of the floating point type converted to and vice versa. -The table below illustrates legal casts between values of -<> and if the cast must be explicit. Each cast -is read as a conversion of row to column. +The table below illustrates allowed casts between values of +<> and which specific casts must be explicit. +Each cast is read as a conversion of row to column. |==== | | byte | short | char | int | long | float | double @@ -73,7 +73,7 @@ is read as a conversion of row to column. *Examples* -* Valid numeric type casts. +* Valid <> casts. + [source,Painless] ---- @@ -99,7 +99,7 @@ is read as a conversion of row to column. assign value of `double 1.0` to `e`; (note the explicit cast is extraneous, and an implicit cast is valid) + -* Invalid numeric type casts resulting in errors. +* Invalid <> casts resulting in errors. + [source,Painless] ---- @@ -121,9 +121,9 @@ is read as a conversion of row to column. [[reference-type-casting]] ==== Reference Type Casting -A reference type cast is the conversion of the value of one -<> to the equivalent value of an inferred or -specified <>. Implicit casts between +A <> cast is the conversion of the value of +one <> to the equivalent value of an inferred +or specified <>. Implicit casts between reference type values are allowed when the reference type being cast *from* is a descendant of the reference type being cast *to*. Explicit casts between reference type values are allowed when the reference type being cast *from* @@ -132,7 +132,7 @@ being cast *to* is a descendant of the reference type being cast *from*. *Examples* -* Valid reference type casts. +* Valid <> casts. + [source,Painless] ---- @@ -163,7 +163,7 @@ being cast *to* is a descendant of the reference type being cast *from*. assign `List reference` to `x`; (note the explicit cast is extraneous, and an implicit cast is valid) + -* Invalid reference type casts resulting in errors. +* Invalid <> casts resulting in errors. + [source,Painless] ---- @@ -189,6 +189,13 @@ being cast *to* is a descendant of the reference type being cast *from*. [[dynamic-type-casting]] ==== Dynamic Type Casting + +A <> cast is the conversion of the value of one +<> to the equivalent value of any inferred or +specified other <> and vice versa. Implicit casts from +<> to the <>. +<>. Use reference type instances to store +and manipulate complex data. Reference type values refer to reference type instances, and multiple reference type values may refer to a single reference type instance. A change to a @@ -128,44 +129,59 @@ function as arguments. The default value for a <> reference type <> is `null`. <> a -<> reference type instance or -<> an existing reference type instance to a reference type -<> for <> later in a -script. <> `null` to a reference type value to indicate the -reference type value refers to no reference type instance. A reference type -instance will be garbage collected by the JVM when no reference type values -refer to that reference type instance. - -Reference type objects can contain member fields, member methods, and -constructors. Member fields are named and typed pieces of data that are read -and written to using the <>. Member methods are -functions decicated to a single reference type object that can manipulate -member fields and return values. Call member methods using the -<>. Constructors are a special type of function -used to allocate a reference type instance using the -<>. - -Reference type objects can have both static and non-static members (member -fields and member methods). <> and -<> static members of a reference type object without -allocating a reference type instance using the reference type object name -as the <> in place of a reference type value. -Static members are singletons per reference type object. Non-static members are -specific to a reference type instance. <> and -<> non-static members on a reference type value referring -to an allocated reference type instance. - -A reference type can contain the following: - -* zero to many <> static member fields -* zero to many <> non-static member fields -* zero to many reference type static member fields -* zero to many reference type non-static member fields -* zero to many <> static member fields -* zero to many <> non-static member fields -* zero to many static member methods -* zero to many non-static member methods -* zero to many constructors +<> reference type instance or an existing +reference type value to a reference type <> for +<> within a script. <> `null` to a +reference type <> to indicate the reference type +value refers to no reference type instance. The JVM will garbage collect a +reference type instance when no reference type values refer to that reference +type instance. + +A reference type object specifies zero-to-many of each of the following: + +static member fields:: + +Static member fields are named and <> pieces of data +specific to a single reference type object. Each reference type *object* +contains one set of data representative of its static member fields. Use the +<> in correspondence with the reference type +object name to access static member fields for reading and writing to a +specific reference type *object*. No reference type instance allocation is +necessary to use static member fields. + +non-static member fields:: + +Non-static member fields are named and <> pieces of data +specified by a reference type object. Each reference type *instance* contains +one set of data representative of its reference type object's non-static member +fields. Use the <> for reading and writing to +non-static member fields of a specific reference type *instance*. An allocated +reference type instance is required to use non-static member fields. + +static member methods:: + +Static member methods are functions specific to a single reference type +*object*. Use the <> in +correspondence with the reference type object name to invoke static member +methods. No reference type instance allocation is necessary to use static +member methods. + +non-static member methods:: + +Non-static member methods are functions specified by a reference type object +and called on a specific reference type *instance*. Non-static member methods +called on a specific reference type instance may read from and write to +non-static member fields of that specific reference type instance. Use the +<> in correspondence with a +specific reference type instance to invoke non-static member methods. An +allocated reference type instance is required to use non-static member methods. + +constructors:: + +Constructors are a special type of function specific to a reference type +*object* used to allocate reference type instances of that reference type +object. Use the <> to +allocate a reference type instance. Reference type objects support a basic inheritance model. Consider types A and B. Type A is considered to be a parent of B, and B a child of A, if B inherits @@ -189,7 +205,7 @@ relationships. + <1> declare `List l`; allocate `ArrayList` instance -> `ArrayList reference`; - implicit cast value of `Arraylist reference` to value of `List reference` + implicit cast value of `ArrayList reference` to value of `List reference` -> `List reference`; assign value of `List reference` to `l` <2> access `l` -> `List reference`; From 19abc562fc1979ba8ace3a4566014a5ac84e646f Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Mon, 14 May 2018 08:48:03 -0700 Subject: [PATCH 17/27] More changes. --- docs/painless/painless-casting.asciidoc | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/painless/painless-casting.asciidoc b/docs/painless/painless-casting.asciidoc index 9f6c95a37543d..655a6720e299f 100644 --- a/docs/painless/painless-casting.asciidoc +++ b/docs/painless/painless-casting.asciidoc @@ -180,7 +180,8 @@ being cast *to* is a descendant of the reference type being cast *from*. <2> declare `ArrayList y`; access `x` -> `List reference`; *error* -> cannot implicit cast `List reference` to `ArrayList reference`; - (note an explicit is valid since `ArrayList` is a descendant of `List`) + (note an explicit cast is valid since `ArrayList` is a descendant of + `List`) <3> declare `ArrayList y`; access `x` -> `List reference`; *error* -> cannot explicit cast `List reference` to `Map reference`; @@ -192,9 +193,9 @@ being cast *to* is a descendant of the reference type being cast *from*. A <> cast is the conversion of the value of one <> to the equivalent value of any inferred or -specified other <> and vice versa. Implicit casts from -<> to the <> or vice versa. Implicit casts from +<> to the <>, `def`, are +always allowed. All primitive and reference types can always be implicitly cast to `def`. While it is possible to explicitly cast to `def`, it is not necessary. From 0cb3e66fc719d67e49e23d2174c97f469f7f78cf Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Mon, 14 May 2018 13:27:09 -0700 Subject: [PATCH 18/27] More fixes. --- docs/painless/painless-casting.asciidoc | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/painless/painless-casting.asciidoc b/docs/painless/painless-casting.asciidoc index 655a6720e299f..e7f44ec69bd60 100644 --- a/docs/painless/painless-casting.asciidoc +++ b/docs/painless/painless-casting.asciidoc @@ -193,18 +193,21 @@ being cast *to* is a descendant of the reference type being cast *from*. A <> cast is the conversion of the value of one <> to the equivalent value of any inferred or -specified other <> or vice versa. Implicit casts from +specified other <> or vice versa. + +Implicit casts from <> to the +<>, `def`, are always allowed. Explicit casts from <> to the <>, `def`, are -always allowed. +allowed but never necessary. -All primitive and reference types can always be implicitly cast to -`def`. While it is possible to explicitly cast to `def`, it is not necessary. +Implicit and explicit casts from the >, `def`, to +<> are allowed if and only if the cast would be +allowed . However, it is not always possible to implicitly cast a `def` to other primitive and reference types. An explicit cast is required if an explicit cast would normally be required between the non-def types. - *Examples:* [source,Java] ---- From 507ac487061dfd98437aa6e5f68cc99457c1c2f0 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Mon, 14 May 2018 17:16:12 -0700 Subject: [PATCH 19/27] More example clean up. --- docs/painless/painless-casting.asciidoc | 51 +++++++++++----- docs/painless/painless-types.asciidoc | 71 ++++++++++++++++++----- docs/painless/painless-variables.asciidoc | 18 +++--- 3 files changed, 103 insertions(+), 37 deletions(-) diff --git a/docs/painless/painless-casting.asciidoc b/docs/painless/painless-casting.asciidoc index e7f44ec69bd60..2b435c4bed45c 100644 --- a/docs/painless/painless-casting.asciidoc +++ b/docs/painless/painless-casting.asciidoc @@ -20,7 +20,7 @@ cast: '(' TYPE ')' expression *Examples* -* General casts. +* Valid general casts. + [source,Painless] ---- @@ -192,24 +192,47 @@ being cast *to* is a descendant of the reference type being cast *from*. ==== Dynamic Type Casting A <> cast is the conversion of the value of one -<> to the equivalent value of any inferred or -specified other <> or vice versa. +<>, `def`, to the equivalent value of any inferred +or specified other <> or vice versa. -Implicit casts from <> to the -<>, `def`, are always allowed. Explicit casts from -<> to the <>, `def`, are +Implicit casts from <> value to a +<> value are always allowed. Explicit casts from +<> value to a <> value are allowed but never necessary. -Implicit and explicit casts from the >, `def`, to -<> are allowed if and only if the cast would be -allowed . +Implicit and explicit casts from a >, value to +<> value are allowed if and only if the cast is +normally allowed based on the current type value the +> value represents. -However, it is not always possible to implicitly cast a `def` to other -primitive and reference types. An explicit cast is required if an explicit -cast would normally be required between the non-def types. +*Examples* ++ +* Examples of casting <> to the + <>. ++ +[source,Painless] +---- +def d0 = 3; +d0 = new ArrayList(); +Object m = new HashMap(); +def d1 = m; +int i = d1.size(); +---- ++ +* Examples of casting from the <> to + <>. ++ +[source,Painless] +---- +---- ++ +* Examples of errors casting with <>. ++ +[source,Painless] +---- +---- -*Examples:* -[source,Java] +[source,Painless] ---- def x; // Declare def variable x and set it to null x = 3; // Set the def variable x to the literal 3 with an implicit diff --git a/docs/painless/painless-types.asciidoc b/docs/painless/painless-types.asciidoc index 135c066ac1af0..46d0276021409 100644 --- a/docs/painless/painless-types.asciidoc +++ b/docs/painless/painless-types.asciidoc @@ -272,9 +272,11 @@ relationships. [[dynamic-types]] ==== Dynamic Types -Dynamic types can represent values of any primitive type or reference type -under a single type name `def`. The `def` type mimics the behavior of whatever -value is currently represented. +Use dynamic type values to represent the values of any primitive type or +reference type under a single type name `def`. A `def` type value mimics +the behavior of whatever value it currently represents and will always +represent the child-most descendant type value of any value when used in +<> and statements. Internally, if a `def` type value is a primitive type value, the value is converted (<>) to the corresponding reference type @@ -303,13 +305,41 @@ reference types directly when performance is critical. ---- + <1> declare `def dp`; - assign value of `int 1` to `dp` + implicit cast value of `int 1` to value of `def` -> `def`; + assign value of `def` to `dp` <2> declare `def dr`; allocate `ArrayList` instance -> `ArrayList reference`; - assign value of `ArrayList reference` to `dr` -<3> access `dp` -> `int 1`; - assign value of `int 1` to `dr`; - (note the switch in type of `dr` from `ArrayList` to `int`) + implicit cast value of `ArrayList reference` to value of `def` -> `def`; + assign value of `def` to `dr` +<3> access `dp` -> `def`; + assign value of `def` to `dr`; + (note the switch in type `dr` represents from `ArrayList` to `int`) ++ +* A `def` type value representing the child-most descendant of a value. ++ +[source,Painless] +---- +<1> Object l = new ArrayList(); +<2> def d = l; +<3> d.ensureCapacity(10); +---- ++ +<1> declare `Object l`; + allocate `ArrayList` instance -> `ArrayList reference`; + implicit cast value of `ArrayList reference` to value of `Object reference` + -> `Object reference`; + assign value of `Object reference` to `l` +<2> declare `def d`; + access `l` -> `Object reference`; + implicit cast value of `Object reference` to value of `def` -> `def`; + assign value of `def` to `d`; +<3> access `d` -> `def`; + implicit cast value of `def` to value of `ArrayList reference` + -> `ArrayList reference`; + call `ensureCapacity` on `ArrayList reference` with arguments (`int 10`); + (note value of `def` was implicit cast to value of `ArrayList reference` + since ArrayList` is the child-most descendant type value that the + `def` type value represents) [[string-type]] ==== String Type @@ -409,10 +439,17 @@ the array type `int[][]`. <3> declare `def z`; allocate `1-d float array` instance with `length [5]` -> `1-d float array reference`; - assign value of `1-d float array reference` to `z` -<4> assign value of `float 1.0` to `index [9]` of `y` -<5> access `index [9]` of `y` -> `float 1.0`; - assign `float 1.0` to `index [0]` of `z` + implicit cast value of `1-d float array reference` to value of `def` + -> `def`; + assign value of `def` to `z` +<4> access `y` -> `1-d float array reference`; + assign value of `float 1.0` to `index [9]` of `1-d float array reference` +<5> access `y` -> `1-d float array reference @1`; + access `index [9]` of `1-d float array reference @1` -> `float 1.0`; + access `z` -> `def`; + implicit cast value of `def` to value of `1-d float array reference @2` + -> `1-d float array reference @2` + assign `float 1.0` to `index [0]` of `1-d float array reference @2` + * Use of a multi-dimensional array. + @@ -425,9 +462,11 @@ the array type `int[][]`. + <1> declare `int[][][] ia`; allocate `3-d int array` instance with length `[2, 3, 4]` - -> `3-d float array reference`; - assign value of `3-d float array reference` to `ia3` -<2> assign value of `int 99` to `index [1, 2, 3]` of `ia3` + -> `3-d int array reference`; + assign value of `3-d int array reference` to `ia3` +<2> access `ia3` -> `3-d int array reference`; + assign value of `int 99` to `index [1, 2, 3]` of `3-d int array reference` <3> declare `int i`; - access `index [1, 2, 3]` of `ia3` -> `int 99`; + access `ia3` -> `3-d int array reference`; + access `index [1, 2, 3]` of `3-d int array reference` -> `int 99`; assign value of `int 99` to `i` \ No newline at end of file diff --git a/docs/painless/painless-variables.asciidoc b/docs/painless/painless-variables.asciidoc index 922105386b0ab..09d8898739387 100644 --- a/docs/painless/painless-variables.asciidoc +++ b/docs/painless/painless-variables.asciidoc @@ -106,7 +106,7 @@ assignment: ID '=' expression assign value of `double 2.0` to `j` + * Assignment of one variable to another using -<>. + <>. + [source,Painless] ---- @@ -121,7 +121,7 @@ assignment: ID '=' expression assign value of `int 10` to `j` + * Assignment with <> using the -<>. + <>. + [source,Painless] ---- @@ -139,7 +139,7 @@ assignment: ID '=' expression assign value of `Map reference` to `m` + * Assignment of one variable to another using -<>. + <>. + [source,Painless] ---- @@ -165,7 +165,7 @@ assignment: ID '=' expression (note `l`, `k`, and `m` refer to the same instance) + * Assignment with the <> using the -<>. + <>. + [source,Painless] ---- @@ -183,7 +183,8 @@ assignment: ID '=' expression <2> allocate `1-d int array` instance with `length [2]` -> `1-d int array reference`; assign value of `1-d int array reference` to `ia1` -<3> assign value of `int 1` to `index [0]` of `ia1` +<3> access `ia1` -> `1-d int array reference`; + assign value of `int 1` to `index [0]` of `1-d int array reference` <4> declare `int[] ib1`; access `ia1` -> `1-d int array reference`; assign value of `1-d int array reference` to `ib1`; @@ -192,7 +193,10 @@ assignment: ID '=' expression allocate `2-d int array` instance with `length [2, 5]` -> `2-d int array reference`; assign value of `2-d int array reference` to `ic2` -<6> assign value of `int 2` to `index [1, 3]` of `ic2` +<6> access `ic2` -> `2-d int array reference`; + assign value of `int 2` to `index [1, 3]` of `2-d int array reference` <7> access `ia1` -> `1-d int array reference`; - assign value of `1-d int array reference` to `index [0]` of `ic2`; + access `ic2` -> `2-d int array reference`; + assign value of `1-d int array reference` to + `index [0]` of `2-d int array reference`; (note `ia1`, `ib1`, and `index [0]` of `ia2` refer to the same instance) From 7ad4ebb92ea2d4f10a7ced0b313d59713bb68d67 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Mon, 14 May 2018 22:01:03 -0700 Subject: [PATCH 20/27] More changes. --- docs/painless/painless-casting.asciidoc | 149 +++++++++++++++++----- docs/painless/painless-literals.asciidoc | 16 +-- docs/painless/painless-types.asciidoc | 46 +++---- docs/painless/painless-variables.asciidoc | 14 +- 4 files changed, 151 insertions(+), 74 deletions(-) diff --git a/docs/painless/painless-casting.asciidoc b/docs/painless/painless-casting.asciidoc index 2b435c4bed45c..6f6f5c26f9324 100644 --- a/docs/painless/painless-casting.asciidoc +++ b/docs/painless/painless-casting.asciidoc @@ -38,7 +38,7 @@ cast: '(' TYPE ')' expression -> `Map reference`; assign value of `Map reference` to `m` <3> declare `HashMap hm`; - access `m` -> `Map reference`; + access value of `m` -> `Map reference`; explicit cast value of `Map reference` to value of `HashMap reference` -> `HashMap reference`; assign value of `HashMap reference` to `hm` @@ -86,15 +86,15 @@ Each cast is read as a conversion of row to column. <1> declare `int a`; assign `int 1` to `a` <2> declare `long b`; - access `a` -> `int 1`; + access value of `a` -> `int 1`; implicit cast value of `int 1` to value of `long 1` -> `long 1`; assign value of `long 1` to `b` <3> declare `short c`; - access `b` -> `long 1`; + access value of `b` -> `long 1`; explicit cast value of `long 1` to value of `short 1` -> `short 1`; assign `short 1` value to `c` <4> declare `double e`; - access `a` -> `int 1`; + access value of `a` -> `int 1`; explicit cast value of `int 1` to `double 1.0`; assign value of `double 1.0` to `e`; (note the explicit cast is extraneous, and an implicit cast is valid) @@ -114,7 +114,7 @@ Each cast is read as a conversion of row to column. <2> declare `int b`; assign `int 2` to `b` <3> declare byte `c`; - access `b` -> `int 2`; + access value of `b` -> `int 2`; *error* -> cannot implicit cast value of `int 2` to value of `byte 2`; (note an explicit cast is valid) @@ -148,16 +148,16 @@ being cast *to* is a descendant of the reference type being cast *from*. <2> declare `ArrayList y`; allocate `ArrayList` instance -> `ArrayList reference`; assign value of `ArrayList reference` to `y`; -<3> access `y` -> `ArrayList reference`; +<3> access value of `y` -> `ArrayList reference`; implicit cast value of `ArrayList reference` to value of `List reference` -> `List reference`; assign `List reference` to `x`; (note `ArrayList` is a descendant of `List`) -<4> access `x` -> `List reference`; +<4> access value of `x` -> `List reference`; explicit cast value of `List reference` to value of `ArrayList reference` -> `ArrayList reference`; assign `ArrayList reference` to `y`; -<5> access `y` -> `ArrayList reference`; +<5> access value of `y` -> `ArrayList reference`; explicit cast value of `ArrayList reference` to value of `List reference` -> `List reference`; assign `List reference` to `x`; @@ -178,12 +178,12 @@ being cast *to* is a descendant of the reference type being cast *from*. -> `List reference`; assign `List reference` to `x` <2> declare `ArrayList y`; - access `x` -> `List reference`; + access value of `x` -> `List reference`; *error* -> cannot implicit cast `List reference` to `ArrayList reference`; (note an explicit cast is valid since `ArrayList` is a descendant of `List`) <3> declare `ArrayList y`; - access `x` -> `List reference`; + access value of `x` -> `List reference`; *error* -> cannot explicit cast `List reference` to `Map reference`; (note no cast would be valid since neither `List` nor `Map` is a descendant of the other) @@ -212,48 +212,137 @@ normally allowed based on the current type value the + [source,Painless] ---- -def d0 = 3; -d0 = new ArrayList(); -Object m = new HashMap(); -def d1 = m; -int i = d1.size(); +<1> def d0 = 3; +<2> d0 = new ArrayList(); +<3> Object o = new HashMap(); +<4> def d1 = o; +<5> int i = d1.size(); ---- + +<1> declare `def d0`; + implicit cast value of `int 3` to `def` + assign value of `int 3` to `d0` +<2> allocate `ArrayList` instance -> `ArrayList reference`; + implicit cast value of `ArrayList reference` to value of `def` -> `def`; + assign value of `def` to `d0` +<3> declare `Object o`; + allocate `HashMap` instance -> `HashMap reference`; + implicit cast value of `HashMap reference` to value of `Object reference` + -> `Object reference`; + assign value of `Object reference` to `o` +<4> declare `def d1`; + access value of `o` -> `Object reference`; + implicit cast value of `Object reference` to value of `def` -> `def`; + assign `def` to `d1` +<5> declare `int i`; + access value of `d1` -> `def`; + implicit cast value of `def` to value of `HashMap reference` + -> HashMap reference`; + call `size` on `HashMap reference` -> `int 0`; + assign `int 0` to `i`; + (note value of `def` was implicit cast to value of `HashMap reference` + since `HashMap` is the child-most descendant type value that the + `def` type value represents) ++ * Examples of casting from the <> to <>. + [source,Painless] ---- +<1> def d = 1.0; +<2> int i = (int)d; +<3> d = 1; +<4> float f = d; +<5> d = new ArrayList(); +<6> List l = d; ---- + +<1> declare `def d`; + implicit cast value of `double 1.0` to value of `def` -> `def`; + assign value of `def` to `d` +<2> declare `int i`; + access value of `d` -> `def`; + implicit cast value of `def` to value of `double 1.0` -> `double 1.0`; + explicit cast value of `double 1.0` to value of `int 1` -> `int 1`; + assign value of `int 1` to `i`; + (note the explicit cast is necessary since a `double` value cannot be + converted to an `int` value implicitly) +<3> assign value of `int 1` to `d`; + (note the switch in the type `d` represents from `double` to `int`) +<4> declare `float i`; + access value of `d` -> `def`; + implicit cast value of `def` to value of `int 1` -> `int 1`; + implicit cast value of `int 1` to value of `float 1.0` -> `float 1.0`; + assign value of `float 1.0` to `f` +<5> allocate `ArrayList` instance -> `ArrayList reference`; + assign value of `ArrayList reference` to `d`; + (note the switch in the type `d` represents from `int` to `ArrayList`) +<6> declare `List l`; + access value of `d` -> `def`; + implicit cast value of `def` to value of `ArrayList reference` + -> `ArrayList reference`; + implicit cast value of `ArrayList reference` to value of `List reference` + -> `List reference`; + assign value of `List reference` to `l` ++ * Examples of errors casting with <>. + [source,Painless] ---- +<1> def d = 1; +<2> short s = d; // error +<3> d = new HashMap(); +<4> List l = d; // error ---- +<1> declare `def d`; + implicit cast value of `int 1` to value of `def` -> `def`; + assign value of `def` to `d` +<2> declare `short s`; + access value of `d` -> `def`; + implicit cast value of `def` to value of `int 1` -> `int 1`; + *error* -> cannot implicit cast value of `int 1` to value of `short 1`; + (note an explicit cast is valid) +<3> allocate `HashMap` instance -> `HashMap reference`; + implicit cast value of `HashMap reference` to value of `def` -> `def`; + assign value of `def` to `d` +<4> declare `List l`; + access value of `d` -> `def`; + implicit cast value of `def` to value of `HashMap reference`; + *error* -> cannot implicit cast `HashMap reference` to `List reference`; + (note no cast would be valid since neither `HashMap` nor `List` is a + descendant of the other) + +[[string-character-casting]] +==== String to Character Casting + +Use the <> to convert +<> values into <> values. Use only +<> values one character in length for this conversion or +an error will occur. +*Examples* + +* Casting <> into <> values. ++ [source,Painless] ---- -def x; // Declare def variable x and set it to null -x = 3; // Set the def variable x to the literal 3 with an implicit - // cast from int to def -double a = x; // Declare double variable a and set it to def variable x, - // which contains a double -int b = x; // ERROR: Results in a run-time error because an explicit cast is - // required to cast from a double to an int -int c = (int)x; // Declare int variable c, explicitly cast def variable x to an - // int, and assign x to c +<1> char c = (char)"C" +<2> c = (char)'c' ---- - -[[character-string-casting]] -==== Character-String Casting -* Casting a <> value into a <> value. ++ +<1> a +<2> a ++ +* Casting a <> value into a <> + value. + [source,Painless] ---- -String s = "s"; -char c = (char)s; +<1> String s = "s"; +<2> char c = (char)s; ---- +<1> a +<2> a [[boxing-unboxing]] ==== Boxing and Unboxing diff --git a/docs/painless/painless-literals.asciidoc b/docs/painless/painless-literals.asciidoc index e408365f805c1..2588b964cbf32 100644 --- a/docs/painless/painless-literals.asciidoc +++ b/docs/painless/painless-literals.asciidoc @@ -118,17 +118,5 @@ STRING: ( '"' ( '\\"' | '\\\\' | ~[\\"] )*? '"' ) ==== Characters Character literals cannot be specified directly. Instead, use the -<> to convert <> -values into <> values. Use only <> -values one character in length for this conversion or an error will occur. - -*Examples* - -* <> string literals into -<> values. -+ -[source,Painless] ----- -(char)"C" -(char)'c' ----- +<> to convert +<> values into <> values. diff --git a/docs/painless/painless-types.asciidoc b/docs/painless/painless-types.asciidoc index 46d0276021409..7aa8052482a0b 100644 --- a/docs/painless/painless-types.asciidoc +++ b/docs/painless/painless-types.asciidoc @@ -103,7 +103,7 @@ logical quantity with two possible values of `true` and `false` + <1> declare `int i`; assign value of `int 1` to `i` -<2> access `i` -> `int 1`; +<2> access value of `i` -> `int 1`; box value of `int 1` -> `Integer 1 reference`; call `toString` on `Integer 1 reference` -> `String '1'` @@ -208,11 +208,11 @@ relationships. implicit cast value of `ArrayList reference` to value of `List reference` -> `List reference`; assign value of `List reference` to `l` -<2> access `l` -> `List reference`; +<2> access value of `l` -> `List reference`; implicit cast value of `int 1` to value of `def` -> `def` call `add` on `List reference` with arguments (`def`) <3> declare `int i`; - access `l` -> `List reference`; + access value of `l` -> `List reference`; call `get` on `List reference` with arguments (`int 0`) -> `def`; implicit cast value of `def` to value of `int 1` -> `int 1`; add value of `int 1` and value of `int 2` -> `int 3`; @@ -235,20 +235,20 @@ relationships. -> `List reference`; assign value of `List reference` to `l0` <2> declare `List l1`; - access `l0` -> `List reference`; + access value of `l0` -> `List reference`; assign value of `List reference` to `l1` (note `l0` and `l1` refer to the same instance known as a shallow-copy) -<3> access `l0` -> `List reference`; +<3> access value of `l0` -> `List reference`; implicit cast value of `int 1` to value of `def` -> `def` call `add` on `List reference` with arguments (`def`) -<4> access `l1` -> `List reference`; +<4> access value of `l1` -> `List reference`; implicit cast value of `int 2` to value of `def` -> `def` call `add` on `List reference` with arguments (`def`) <5> declare `int i`; - access `l0` -> `List reference`; + access value of `l0` -> `List reference`; call `get` on `List reference` with arguments (`int 0`) -> `def @0`; implicit cast value of `def @0` to value of `int 1` -> `int 1`; - access `l1` -> `List reference`; + access value of `l1` -> `List reference`; call `get` on `List reference` with arguments (`int 1`) -> `def @1`; implicit cast value of `def @1` to value of `int 2` -> `int 2`; add value of `int 1` and value of `int 2` -> `int 3`; @@ -263,7 +263,7 @@ relationships. ---- + <1> declare `int i`; - access `MAX_VALUE` on `Integer` -> `int 2147483647`; + access value of `MAX_VALUE` on `Integer` -> `int 2147483647`; assign value of `int 2147483647` to `i` <2> declare `long l`; call `parseLong` on `Long` with arguments (`long 123`) -> `long 123`; @@ -311,9 +311,9 @@ reference types directly when performance is critical. allocate `ArrayList` instance -> `ArrayList reference`; implicit cast value of `ArrayList reference` to value of `def` -> `def`; assign value of `def` to `dr` -<3> access `dp` -> `def`; +<3> access value of `dp` -> `def`; assign value of `def` to `dr`; - (note the switch in type `dr` represents from `ArrayList` to `int`) + (note the switch in the type `dr` represents from `ArrayList` to `int`) + * A `def` type value representing the child-most descendant of a value. + @@ -330,10 +330,10 @@ reference types directly when performance is critical. -> `Object reference`; assign value of `Object reference` to `l` <2> declare `def d`; - access `l` -> `Object reference`; + access value of `l` -> `Object reference`; implicit cast value of `Object reference` to value of `def` -> `def`; assign value of `def` to `d`; -<3> access `d` -> `def`; +<3> access value of `d` -> `def`; implicit cast value of `def` to value of `ArrayList reference` -> `ArrayList reference`; call `ensureCapacity` on `ArrayList reference` with arguments (`int 10`); @@ -442,14 +442,14 @@ the array type `int[][]`. implicit cast value of `1-d float array reference` to value of `def` -> `def`; assign value of `def` to `z` -<4> access `y` -> `1-d float array reference`; +<4> access value of `y` -> `1-d float array reference`; assign value of `float 1.0` to `index [9]` of `1-d float array reference` -<5> access `y` -> `1-d float array reference @1`; - access `index [9]` of `1-d float array reference @1` -> `float 1.0`; - access `z` -> `def`; - implicit cast value of `def` to value of `1-d float array reference @2` - -> `1-d float array reference @2` - assign `float 1.0` to `index [0]` of `1-d float array reference @2` +<5> access value of `y` -> `1-d float array reference @0`; + access `index [9]` of `1-d float array reference @0` -> `float 1.0`; + access value of `z` -> `def`; + implicit cast value of `def` to value of `1-d float array reference @1` + -> `1-d float array reference @1`; + assign value of `float 1.0` to `index [0]` of `1-d float array reference @1` + * Use of a multi-dimensional array. + @@ -464,9 +464,9 @@ the array type `int[][]`. allocate `3-d int array` instance with length `[2, 3, 4]` -> `3-d int array reference`; assign value of `3-d int array reference` to `ia3` -<2> access `ia3` -> `3-d int array reference`; +<2> access value of `ia3` -> `3-d int array reference`; assign value of `int 99` to `index [1, 2, 3]` of `3-d int array reference` <3> declare `int i`; - access `ia3` -> `3-d int array reference`; - access `index [1, 2, 3]` of `3-d int array reference` -> `int 99`; + access value of `ia3` -> `3-d int array reference`; + access value of `index [1, 2, 3]` of `3-d int array reference` -> `int 99`; assign value of `int 99` to `i` \ No newline at end of file diff --git a/docs/painless/painless-variables.asciidoc b/docs/painless/painless-variables.asciidoc index 09d8898739387..683acd2dcdf8d 100644 --- a/docs/painless/painless-variables.asciidoc +++ b/docs/painless/painless-variables.asciidoc @@ -155,12 +155,12 @@ assignment: ID '=' expression -> `List reference`; assign value of `List reference` to `l` <2> declare `List k`; - access `l` -> `List reference`; + access value of `l` -> `List reference`; assign value of `List reference` to `k`; (note `l` and `k` refer to the same instance known as a shallow-copy) <3> declare `List m`; assign default value of `null` to `m` -<4> access `k` -> `List reference`; +<4> access value of `k` -> `List reference`; assign value of `List reference` to `m`; (note `l`, `k`, and `m` refer to the same instance) + @@ -183,20 +183,20 @@ assignment: ID '=' expression <2> allocate `1-d int array` instance with `length [2]` -> `1-d int array reference`; assign value of `1-d int array reference` to `ia1` -<3> access `ia1` -> `1-d int array reference`; +<3> access value of `ia1` -> `1-d int array reference`; assign value of `int 1` to `index [0]` of `1-d int array reference` <4> declare `int[] ib1`; - access `ia1` -> `1-d int array reference`; + access value of `ia1` -> `1-d int array reference`; assign value of `1-d int array reference` to `ib1`; (note `ia1` and `ib1` refer to the same instance known as a shallow copy) <5> declare `int[][] ic2`; allocate `2-d int array` instance with `length [2, 5]` -> `2-d int array reference`; assign value of `2-d int array reference` to `ic2` -<6> access `ic2` -> `2-d int array reference`; +<6> access value of `ic2` -> `2-d int array reference`; assign value of `int 2` to `index [1, 3]` of `2-d int array reference` -<7> access `ia1` -> `1-d int array reference`; - access `ic2` -> `2-d int array reference`; +<7> access value of `ia1` -> `1-d int array reference`; + access value of `ic2` -> `2-d int array reference`; assign value of `1-d int array reference` to `index [0]` of `2-d int array reference`; (note `ia1`, `ib1`, and `index [0]` of `ia2` refer to the same instance) From a9c941e8aaeb42c0153791b4ece3f75e86750a3d Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Mon, 14 May 2018 23:41:37 -0700 Subject: [PATCH 21/27] Finished promotion and boxing/unboxing. --- docs/painless/painless-casting.asciidoc | 188 ++++++++++++++++-------- 1 file changed, 129 insertions(+), 59 deletions(-) diff --git a/docs/painless/painless-casting.asciidoc b/docs/painless/painless-casting.asciidoc index 6f6f5c26f9324..45f169ed90f41 100644 --- a/docs/painless/painless-casting.asciidoc +++ b/docs/painless/painless-casting.asciidoc @@ -31,7 +31,7 @@ cast: '(' TYPE ')' expression + <1> declare `int i`; explicit cast value of `long 5` to value of `int 5` -> `int 5`; - assign `int 5` to `i` + assign value of `int 5` to `i` <2> declare `Map m`; allocate `HashMap` instance -> `HashMap reference`; implicit cast value of `HashMap reference` to value of `Map reference` @@ -84,7 +84,7 @@ Each cast is read as a conversion of row to column. ---- + <1> declare `int a`; - assign `int 1` to `a` + assign value of `int 1` to `a` <2> declare `long b`; access value of `a` -> `int 1`; implicit cast value of `int 1` to value of `long 1` -> `long 1`; @@ -92,7 +92,7 @@ Each cast is read as a conversion of row to column. <3> declare `short c`; access value of `b` -> `long 1`; explicit cast value of `long 1` to value of `short 1` -> `short 1`; - assign `short 1` value to `c` + assign value of `short 1` value to `c` <4> declare `double e`; access value of `a` -> `int 1`; explicit cast value of `int 1` to `double 1.0`; @@ -112,7 +112,7 @@ Each cast is read as a conversion of row to column. *error* -> cannot implicit cast value of `double 1.0` to value of `int 1`; (note an explicit cast is valid) <2> declare `int b`; - assign `int 2` to `b` + assign value of `int 2` to `b` <3> declare byte `c`; access value of `b` -> `int 2`; *error* -> cannot implicit cast value of `int 2` to value of `byte 2`; @@ -151,16 +151,16 @@ being cast *to* is a descendant of the reference type being cast *from*. <3> access value of `y` -> `ArrayList reference`; implicit cast value of `ArrayList reference` to value of `List reference` -> `List reference`; - assign `List reference` to `x`; + assign value of `List reference` to `x`; (note `ArrayList` is a descendant of `List`) <4> access value of `x` -> `List reference`; explicit cast value of `List reference` to value of `ArrayList reference` -> `ArrayList reference`; - assign `ArrayList reference` to `y`; + assign value of `ArrayList reference` to `y`; <5> access value of `y` -> `ArrayList reference`; explicit cast value of `ArrayList reference` to value of `List reference` -> `List reference`; - assign `List reference` to `x`; + assign value of `List reference` to `x`; (note the explicit cast is extraneous, and an implicit cast is valid) + * Invalid <> casts resulting in errors. @@ -176,7 +176,7 @@ being cast *to* is a descendant of the reference type being cast *from*. allocate `ArrayList` instance -> `ArrayList reference`; implicit cast value of `ArrayList reference` to value of `List reference` -> `List reference`; - assign `List reference` to `x` + assign value of `List reference` to `x` <2> declare `ArrayList y`; access value of `x` -> `List reference`; *error* -> cannot implicit cast `List reference` to `ArrayList reference`; @@ -206,7 +206,7 @@ normally allowed based on the current type value the > value represents. *Examples* -+ + * Examples of casting <> to the <>. + @@ -220,7 +220,7 @@ normally allowed based on the current type value the ---- + <1> declare `def d0`; - implicit cast value of `int 3` to `def` + implicit cast value of `int 3` to `def`; assign value of `int 3` to `d0` <2> allocate `ArrayList` instance -> `ArrayList reference`; implicit cast value of `ArrayList reference` to value of `def` -> `def`; @@ -233,13 +233,13 @@ normally allowed based on the current type value the <4> declare `def d1`; access value of `o` -> `Object reference`; implicit cast value of `Object reference` to value of `def` -> `def`; - assign `def` to `d1` + assign value of `def` to `d1` <5> declare `int i`; access value of `d1` -> `def`; implicit cast value of `def` to value of `HashMap reference` -> HashMap reference`; call `size` on `HashMap reference` -> `int 0`; - assign `int 0` to `i`; + assign value of `int 0` to `i`; (note value of `def` was implicit cast to value of `HashMap reference` since `HashMap` is the child-most descendant type value that the `def` type value represents) @@ -285,7 +285,7 @@ normally allowed based on the current type value the -> `List reference`; assign value of `List reference` to `l` + -* Examples of errors casting with <>. +* Examples of errors when casting with the <>. + [source,Painless] ---- @@ -330,8 +330,11 @@ an error will occur. <2> c = (char)'c' ---- + -<1> a -<2> a +<1> declare `char c`; + explicit cast value of `String "C"` to value of `char C` -> `char C`; + assign value of `char C` to `c` +<2> explicit cast value of `String 'c'` to value of `char c` -> `char c`; + assign value of `char c` to `c` + * Casting a <> value into a <> value. @@ -341,62 +344,129 @@ an error will occur. <1> String s = "s"; <2> char c = (char)s; ---- -<1> a -<2> a +<1> declare `String s`; + assign value of `String "s"` to `s`; +<2> declare `char c` + access value of `s` -> `String "s"`; + explicit cast value of `String "s"` to value of `char s` -> `char s`; + assign value of `char s` to `c` [[boxing-unboxing]] ==== Boxing and Unboxing -Boxing is where a cast is used to convert a primitive type to its corresponding -reference type. Unboxing is the reverse, converting a reference type to the -corresponding primitive type. - -There are two places Painless performs implicit boxing and unboxing: +Boxing is a special type of cast used to convert a +<> to its corresponding +<>. Unboxing is the reverse used to convert a +<> to its corresponding +<>. + +Implicit boxing/unboxing occurs during the following +<>: + +* Conversions between the <> and + <> will be implicitly boxed/unboxed as + necessary, though this is referred to as an implicit cast throughout the + documentation. +* <>/function call arguments will be implicitly + boxed/unboxed as necessary. +* <> values will be implicitly boxed when a + <> <> is made on a + <> value. + +Explicit boxing/unboxing is not allowed and will result in an error. Use the +reference type API to explicitly convert primitive type values to their +respective reference type values and vice versa. -* When you call methods, Painless automatically boxes and unboxes arguments -so you can specify either primitive types or their corresponding reference -types. -* When you use the `def` type, Painless automatically boxes and unboxes as -needed when converting to and from `def`. - -The casting operator does not support any way to explicitly box a primitive -type or unbox a reference type. - -If a primitive type needs to be converted to a reference type, the Painless -reference type API supports methods that can do that. However, under normal -circumstances this should not be necessary. +*Examples* -*Examples:* -[source,Java] +* Uses of implicit boxing/unboxing. ++ +[source,Painless] +---- +<1> List l = new ArrayList(); +<2> l.add(1); +<3> Integer I = Integer.valueOf(0); +<4> int i = l.get(i); +---- ++ +<1> declare `List l`; + allocate `ArrayList` instance -> `ArrayList reference`; + assign value of `ArrayList reference` to `l`; +<2> access value of `l` -> `List reference`; + implicit cast value of `int 1` to value of `def` -> `def`; + call `add` on `List reference` with arguments (`def`); + (note internally `int 1` is boxed to `Integer 1` to store as a `def` type + value) +<3> declare `Integer I`; + call `valueOf` on `Integer` with arguments of (`int 0`) -> `Integer 0`; + assign value of `Integer 0` to `I`; +<4> declare `int i`; + access value of `I` -> `Integer 0`; + unbox `Integer 0` -> `int 0`; + access value of `l` -> `List reference`; + call `get` on `List reference` with arguments (`int 0`) -> `def`; + implicit cast value of `def` to value of `int 1` -> `int 1`; + assign value of `int 1` to `i`; + (note internally `int 1` is unboxed from `Integer 1` when read from a `def` + type value) ++ +* Uses of invalid boxing/unboxing resulting in errors. ++ +[source,Painless] ---- -Integer x = 1; // ERROR: not a legal implicit cast -Integer y = (Integer)1; // ERROR: not a legal explicit cast -int a = new Integer(1); // ERROR: not a legal implicit cast -int b = (int)new Integer(1); // ERROR: not a legal explicit cast +<1> Integer x = 1; // error +<2> Integer y = (Integer)1; // error +<3> int a = Integer.valueOf(1); // error +<4> int b = (int)Integer.valueOf(1); // error ---- ++ +<1> declare `Integer x`; + *error* -> cannot implicit box `int 1` to `Integer 1` during assignment +<2> declare `Integer y`; + *error* -> cannot explicit box `int 1` to `Integer 1` during assignment +<3> declare `int a`; + call `valueOf` on `Integer` with arguments of (`int 1`) -> `Integer 1`; + *error* -> cannot implicit unbox `Integer 1` to `int 1` during assignment +<4> declare `int a`; + call `valueOf` on `Integer` with arguments of (`int 1`) -> `Integer 1`; + *error* -> cannot explicit unbox `Integer 1` to `int 1` during assignment [[promotion]] ==== Promotion -Promotion is where certain operations require types to be either a minimum -numerical type or for two (or more) types to be equivalent. -The documentation for each operation that has these requirements -includes promotion tables that describe how this is handled. +Promotion is when a value is converted into either a certain type or when +multiple values are converted into equivalent types for use during an +<>. Each <> that +requires promotion will have a promotion table that shows all allowed +conversions. Values can be promoted to the `def` type at compile-time; however, +at run-time, the promoted type of value is derived from what the `def` type +value represents. -When an operation promotes a type or types, the resultant type -of the operation is the promoted type. Types can be promoted to def -at compile-time; however, at run-time, the resultant type will be the -promotion of the types the `def` is representing. +*Examples* -*Examples:* -[source,Java] +* Uses of promotion. ++ +[source,Painless] ---- -2 + 2.0 // Add the literal int 2 and the literal double 2.0. The literal - // 2 is promoted to a double and the resulting value is a double. - -def x = 1; // Declare def variable x and set it to the literal int 1 through - // an implicit cast -x + 2.0F // Add def variable x and the literal float 2.0. - // At compile-time the types are promoted to def. - // At run-time the types are promoted to float. ----- \ No newline at end of file +<1> double d = 2 + 2.0; +<2> def x = 1; +<3> float f = x + 2.0F; +---- +<1> declare `double d`; + promote value of `int 2` and value of `double 2.0 @0` -> `double 2.0 @0`; + implicit cast value of `int 2` to value of `double 2.0 @1` + -> `double 2.0 @1`; + add `double 2.0 @1` and `double 2.0 @0` -> `double 4.0`; + assign value of `double 4.0` to `d` +<2> declare `def x`; + implicit cast value of `int 1` to value of `def` -> `def`; + assign value of `def` to `x`; +<3> declare `float f`; + access value of `x` -> `def`; + implicit cast value of `def` to value of `int 1` -> `int 1`; + promote value of `int 1` and value of `float 2.0` -> `float 2.0`; + implicit cast value of `int 1` to value of `float 1.0` -> `float `1.0`; + add `float 1.0` and `float 2.0` -> `float 3.0`; + assign value of `float 3.0` to `f`; + (note this example illustrates promotion done at run-time as promotion + done at compile-time would have resolved to a `def` type value) \ No newline at end of file From 988fc235b1c5d7fb37ce96d847f2ed954b68e64a Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Fri, 18 May 2018 17:27:35 -0700 Subject: [PATCH 22/27] Cleaned up casting basic on PR comments. --- docs/painless/painless-casting.asciidoc | 360 ++++++++++++------------ 1 file changed, 174 insertions(+), 186 deletions(-) diff --git a/docs/painless/painless-casting.asciidoc b/docs/painless/painless-casting.asciidoc index 45f169ed90f41..d72d12b8f7ee7 100644 --- a/docs/painless/painless-casting.asciidoc +++ b/docs/painless/painless-casting.asciidoc @@ -1,16 +1,17 @@ [[painless-casting]] === Casting -A cast is the conversion of the value of one type to the equivalent value of an -inferred or specified type. Implicit casts are an inferred operation that -automatically convert values between types within a statement or -<> when necessary. Explicit casts are a -specified operation that forcefully convert values between types and are -required when an appropriate type for a statement or -<> cannot be inferred. If there exists no -equivalent value for the type converted to during a cast operation an error -will occur. If an implicit cast is given but an explicit cast is required an -error will occur. +A cast converts the value of an original <> to the +equivalent value of a target <>. An implicit cast infers +the target type and automatically occurs during certain +<>. An explicit cast specifies the target type +and forcefully occurs as its own operation. Use the *cast operator ()* to +specify an explicit cast. + +*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* [source,ANTLR4] @@ -20,7 +21,7 @@ cast: '(' TYPE ')' expression *Examples* -* Valid general casts. +* Valid casts. + [source,Painless] ---- @@ -30,35 +31,29 @@ cast: '(' TYPE ')' expression ---- + <1> declare `int i`; - explicit cast value of `long 5` to value of `int 5` -> `int 5`; - assign value of `int 5` to `i` + explicit cast `long 5` to `int 5` -> `int 5`; + assign `int 5` to `i` <2> declare `Map m`; allocate `HashMap` instance -> `HashMap reference`; - implicit cast value of `HashMap reference` to value of `Map reference` - -> `Map reference`; - assign value of `Map reference` to `m` + implicit cast `HashMap reference` to `Map reference` -> `Map reference`; + assign `Map reference` to `m` <3> declare `HashMap hm`; - access value of `m` -> `Map reference`; - explicit cast value of `Map reference` to value of `HashMap reference` - -> `HashMap reference`; - assign value of `HashMap reference` to `hm` + access `m` -> `Map reference`; + explicit cast `Map reference` to `HashMap reference` -> `HashMap reference`; + assign `HashMap reference` to `hm` [[numeric-type-casting]] ==== Numeric Type Casting -A <> cast is the conversion of the value of one -<> to the equivalent value of an inferred or -specified <>. Casts between values of -<> will result in data loss when the value of -the type converted from is larger than the equivalent value of the type -converted to can accommodate. Casts between values of integral types and values -of floating point types will result in precision loss when the value of the -integral type converted from is unable to accurately represent the equivalent -value of the floating point type converted to and vice versa. +A <> 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 table below illustrates allowed casts between values of -<> and which specific casts must be explicit. -Each cast is read as a conversion of row to column. +The allowed casts for values of each numeric type is shown as a row in the table +below. |==== | | byte | short | char | int | long | float | double @@ -73,7 +68,7 @@ Each cast is read as a conversion of row to column. *Examples* -* Valid <> casts. +* Valid numeric type casts. + [source,Painless] ---- @@ -84,22 +79,22 @@ Each cast is read as a conversion of row to column. ---- + <1> declare `int a`; - assign value of `int 1` to `a` + assign `int 1` to `a` <2> declare `long b`; - access value of `a` -> `int 1`; - implicit cast value of `int 1` to value of `long 1` -> `long 1`; - assign value of `long 1` to `b` + access `a` -> `int 1`; + implicit cast `int 1` to `long 1` -> `long 1`; + assign `long 1` to `b` <3> declare `short c`; - access value of `b` -> `long 1`; - explicit cast value of `long 1` to value of `short 1` -> `short 1`; - assign value of `short 1` value to `c` + access `b` -> `long 1`; + explicit cast `long 1` to `short 1` -> `short 1`; + assign `short 1` value to `c` <4> declare `double e`; - access value of `a` -> `int 1`; - explicit cast value of `int 1` to `double 1.0`; - assign value of `double 1.0` to `e`; - (note the explicit cast is extraneous, and an implicit cast is valid) + access `a` -> `int 1`; + explicit cast `int 1` to `double 1.0`; + assign `double 1.0` to `e`; + (note the explicit cast is extraneous since an implicit cast is valid) + -* Invalid <> casts resulting in errors. +* Invalid numeric type casts resulting in errors. + [source,Painless] ---- @@ -109,30 +104,28 @@ Each cast is read as a conversion of row to column. ---- + <1> declare `int i`; - *error* -> cannot implicit cast value of `double 1.0` to value of `int 1`; + *error* -> cannot implicit cast `double 1.0` to `int 1`; (note an explicit cast is valid) <2> declare `int b`; - assign value of `int 2` to `b` + assign `int 2` to `b` <3> declare byte `c`; - access value of `b` -> `int 2`; - *error* -> cannot implicit cast value of `int 2` to value of `byte 2`; + access `b` -> `int 2`; + *error* -> cannot implicit cast `int 2` to `byte 2`; (note an explicit cast is valid) [[reference-type-casting]] ==== Reference Type Casting -A <> cast is the conversion of the value of -one <> to the equivalent value of an inferred -or specified <>. Implicit casts between -reference type values are allowed when the reference type being cast *from* -is a descendant of the reference type being cast *to*. Explicit casts between -reference type values are allowed when the reference type being cast *from* -is a descendant of the reference type being cast *to* or the reference type -being cast *to* is a descendant of the reference type being cast *from*. +A <> 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 <> casts. +* Valid reference type casts. + [source,Painless] ---- @@ -147,23 +140,21 @@ being cast *to* is a descendant of the reference type being cast *from*. assign default value `null` to `x` <2> declare `ArrayList y`; allocate `ArrayList` instance -> `ArrayList reference`; - assign value of `ArrayList reference` to `y`; -<3> access value of `y` -> `ArrayList reference`; - implicit cast value of `ArrayList reference` to value of `List reference` - -> `List reference`; - assign value of `List reference` to `x`; + assign `ArrayList reference` to `y`; +<3> access `y` -> `ArrayList reference`; + implicit cast `ArrayList reference` to `List reference` -> `List reference`; + assign `List reference` to `x`; (note `ArrayList` is a descendant of `List`) -<4> access value of `x` -> `List reference`; - explicit cast value of `List reference` to value of `ArrayList reference` +<4> access `x` -> `List reference`; + explicit cast `List reference` to `ArrayList reference` -> `ArrayList reference`; - assign value of `ArrayList reference` to `y`; -<5> access value of `y` -> `ArrayList reference`; - explicit cast value of `ArrayList reference` to value of `List reference` - -> `List reference`; - assign value of `List reference` to `x`; + assign `ArrayList reference` to `y`; +<5> access `y` -> `ArrayList reference`; + explicit cast `ArrayList reference` to `List reference` -> `List reference`; + assign `List reference` to `x`; (note the explicit cast is extraneous, and an implicit cast is valid) + -* Invalid <> casts resulting in errors. +* Invalid reference type casts resulting in errors. + [source,Painless] ---- @@ -174,16 +165,14 @@ being cast *to* is a descendant of the reference type being cast *from*. + <1> declare `List x`; allocate `ArrayList` instance -> `ArrayList reference`; - implicit cast value of `ArrayList reference` to value of `List reference` - -> `List reference`; - assign value of `List reference` to `x` + implicit cast `ArrayList reference` to `List reference` -> `List reference`; + assign `List reference` to `x` <2> declare `ArrayList y`; - access value of `x` -> `List reference`; + access `x` -> `List reference`; *error* -> cannot implicit cast `List reference` to `ArrayList reference`; - (note an explicit cast is valid since `ArrayList` is a descendant of - `List`) + (note an explicit cast is valid since `ArrayList` is a descendant of `List`) <3> declare `ArrayList y`; - access value of `x` -> `List reference`; + access `x` -> `List reference`; *error* -> cannot explicit cast `List reference` to `Map reference`; (note no cast would be valid since neither `List` nor `Map` is a descendant of the other) @@ -191,24 +180,21 @@ being cast *to* is a descendant of the reference type being cast *from*. [[dynamic-type-casting]] ==== Dynamic Type Casting -A <> cast is the conversion of the value of one -<>, `def`, to the equivalent value of any inferred -or specified other <> or vice versa. +A <> cast converts the value of an original +`def` type to the equivalent value of any target type or converts the value of +any original type to the equivalent value of a target `def` type. -Implicit casts from <> value to a -<> value are always allowed. Explicit casts from -<> value to a <> value are -allowed but never necessary. +An implicit cast from any original type value to a `def` type value is always +allowed. An explicit cast from any original type value to a `def` type value is +always allowed but never necessary. -Implicit and explicit casts from a >, value to -<> value are allowed if and only if the cast is -normally allowed based on the current type value the -> value represents. +An implicit or explicit cast from an original `def` type value to +any target type value is allowed if and only if the cast is normally allowed +based on the current type value the `def` type value represents. *Examples* -* Examples of casting <> to the - <>. +* Valid dynamic type casts with any original type to a target `def` type. + [source,Painless] ---- @@ -220,32 +206,30 @@ normally allowed based on the current type value the ---- + <1> declare `def d0`; - implicit cast value of `int 3` to `def`; - assign value of `int 3` to `d0` + implicit cast `int 3` to `def`; + assign `int 3` to `d0` <2> allocate `ArrayList` instance -> `ArrayList reference`; - implicit cast value of `ArrayList reference` to value of `def` -> `def`; - assign value of `def` to `d0` + implicit cast `ArrayList reference` to `def` -> `def`; + assign `def` to `d0` <3> declare `Object o`; allocate `HashMap` instance -> `HashMap reference`; - implicit cast value of `HashMap reference` to value of `Object reference` + implicit cast `HashMap reference` to `Object reference` -> `Object reference`; - assign value of `Object reference` to `o` + assign `Object reference` to `o` <4> declare `def d1`; - access value of `o` -> `Object reference`; - implicit cast value of `Object reference` to value of `def` -> `def`; - assign value of `def` to `d1` + access `o` -> `Object reference`; + implicit cast `Object reference` to `def` -> `def`; + assign `def` to `d1` <5> declare `int i`; - access value of `d1` -> `def`; - implicit cast value of `def` to value of `HashMap reference` - -> HashMap reference`; + access `d1` -> `def`; + implicit cast `def` to `HashMap reference` -> HashMap reference`; call `size` on `HashMap reference` -> `int 0`; - assign value of `int 0` to `i`; - (note value of `def` was implicit cast to value of `HashMap reference` - since `HashMap` is the child-most descendant type value that the - `def` type value represents) + assign `int 0` to `i`; + (note `def` was implicit cast to `HashMap reference` since `HashMap` is the + child-most descendant type value that the `def` type value + represents) + -* Examples of casting from the <> to - <>. +* Valid dynamic type casts with an original `def` type to any target type. + [source,Painless] ---- @@ -258,34 +242,32 @@ normally allowed based on the current type value the ---- + <1> declare `def d`; - implicit cast value of `double 1.0` to value of `def` -> `def`; - assign value of `def` to `d` + implicit cast `double 1.0` to `def` -> `def`; + assign `def` to `d` <2> declare `int i`; - access value of `d` -> `def`; - implicit cast value of `def` to value of `double 1.0` -> `double 1.0`; - explicit cast value of `double 1.0` to value of `int 1` -> `int 1`; - assign value of `int 1` to `i`; + access `d` -> `def`; + implicit cast `def` to `double 1.0` -> `double 1.0`; + explicit cast `double 1.0` to `int 1` -> `int 1`; + assign `int 1` to `i`; (note the explicit cast is necessary since a `double` value cannot be converted to an `int` value implicitly) -<3> assign value of `int 1` to `d`; +<3> assign `int 1` to `d`; (note the switch in the type `d` represents from `double` to `int`) <4> declare `float i`; - access value of `d` -> `def`; - implicit cast value of `def` to value of `int 1` -> `int 1`; - implicit cast value of `int 1` to value of `float 1.0` -> `float 1.0`; - assign value of `float 1.0` to `f` + access `d` -> `def`; + implicit cast `def` to `int 1` -> `int 1`; + implicit cast `int 1` to `float 1.0` -> `float 1.0`; + assign `float 1.0` to `f` <5> allocate `ArrayList` instance -> `ArrayList reference`; - assign value of `ArrayList reference` to `d`; + assign `ArrayList reference` to `d`; (note the switch in the type `d` represents from `int` to `ArrayList`) <6> declare `List l`; - access value of `d` -> `def`; - implicit cast value of `def` to value of `ArrayList reference` - -> `ArrayList reference`; - implicit cast value of `ArrayList reference` to value of `List reference` - -> `List reference`; - assign value of `List reference` to `l` + access `d` -> `def`; + implicit cast `def` to `ArrayList reference` -> `ArrayList reference`; + implicit cast `ArrayList reference` to `List reference` -> `List reference`; + assign `List reference` to `l` + -* Examples of errors when casting with the <>. +* Invalid dynamic type casts resulting in errors. + [source,Painless] ---- @@ -295,19 +277,19 @@ normally allowed based on the current type value the <4> List l = d; // error ---- <1> declare `def d`; - implicit cast value of `int 1` to value of `def` -> `def`; - assign value of `def` to `d` + implicit cast `int 1` to `def` -> `def`; + assign `def` to `d` <2> declare `short s`; - access value of `d` -> `def`; - implicit cast value of `def` to value of `int 1` -> `int 1`; - *error* -> cannot implicit cast value of `int 1` to value of `short 1`; + access `d` -> `def`; + implicit cast `def` to `int 1` -> `int 1`; + *error* -> cannot implicit cast `int 1` to `short 1`; (note an explicit cast is valid) <3> allocate `HashMap` instance -> `HashMap reference`; - implicit cast value of `HashMap reference` to value of `def` -> `def`; - assign value of `def` to `d` + implicit cast `HashMap reference` to `def` -> `def`; + assign `def` to `d` <4> declare `List l`; - access value of `d` -> `def`; - implicit cast value of `def` to value of `HashMap reference`; + access `d` -> `def`; + implicit cast `def` to `HashMap reference`; *error* -> cannot implicit cast `HashMap reference` to `List reference`; (note no cast would be valid since neither `HashMap` nor `List` is a descendant of the other) @@ -315,14 +297,16 @@ normally allowed based on the current type value the [[string-character-casting]] ==== String to Character Casting -Use the <> to convert -<> values into <> values. Use only -<> values one character in length for this conversion or -an error will occur. +Use the <> to convert a +<> value into a <> value. + +*Errors* + +* If the String type value isn't one character in length. *Examples* -* Casting <> into <> values. +* Casting <> into char type values. + [source,Painless] ---- @@ -331,13 +315,12 @@ an error will occur. ---- + <1> declare `char c`; - explicit cast value of `String "C"` to value of `char C` -> `char C`; - assign value of `char C` to `c` -<2> explicit cast value of `String 'c'` to value of `char c` -> `char c`; - assign value of `char c` to `c` + explicit cast `String "C"` to `char C` -> `char C`; + assign `char C` to `c` +<2> explicit cast `String 'c'` to `char c` -> `char c`; + assign `char c` to `c` + -* Casting a <> value into a <> - value. +* Casting a String type value into a char type value. + [source,Painless] ---- @@ -345,11 +328,11 @@ an error will occur. <2> char c = (char)s; ---- <1> declare `String s`; - assign value of `String "s"` to `s`; + assign `String "s"` to `s`; <2> declare `char c` - access value of `s` -> `String "s"`; - explicit cast value of `String "s"` to value of `char s` -> `char s`; - assign value of `char s` to `c` + access `s` -> `String "s"`; + explicit cast `String "s"` to `char s` -> `char s`; + assign `char s` to `c` [[boxing-unboxing]] ==== Boxing and Unboxing @@ -357,25 +340,27 @@ an error will occur. Boxing is a special type of cast used to convert a <> to its corresponding <>. Unboxing is the reverse used to convert a -<> to its corresponding -<>. +reference type to its corresponding primitive type. Implicit boxing/unboxing occurs during the following <>: * Conversions between the <> and - <> will be implicitly boxed/unboxed as + primitive types will be implicitly boxed/unboxed as necessary, though this is referred to as an implicit cast throughout the documentation. * <>/function call arguments will be implicitly boxed/unboxed as necessary. -* <> values will be implicitly boxed when a - <> <> is made on a - <> value. +* Primitive type values will be implicitly boxed when a reference type method + call is invoked on a primitive type value. + +Explicit boxing/unboxing is not allowed. Use the reference type API to +explicitly convert primitive type values to their respective reference type +values and vice versa. + +*Errors* -Explicit boxing/unboxing is not allowed and will result in an error. Use the -reference type API to explicitly convert primitive type values to their -respective reference type values and vice versa. +* If an explicit cast is made to box/unbox a primitive type. *Examples* @@ -391,22 +376,22 @@ respective reference type values and vice versa. + <1> declare `List l`; allocate `ArrayList` instance -> `ArrayList reference`; - assign value of `ArrayList reference` to `l`; -<2> access value of `l` -> `List reference`; - implicit cast value of `int 1` to value of `def` -> `def`; + assign `ArrayList reference` to `l`; +<2> access `l` -> `List reference`; + implicit cast `int 1` to `def` -> `def`; call `add` on `List reference` with arguments (`def`); (note internally `int 1` is boxed to `Integer 1` to store as a `def` type value) <3> declare `Integer I`; call `valueOf` on `Integer` with arguments of (`int 0`) -> `Integer 0`; - assign value of `Integer 0` to `I`; + assign `Integer 0` to `I`; <4> declare `int i`; - access value of `I` -> `Integer 0`; + access `I` -> `Integer 0`; unbox `Integer 0` -> `int 0`; - access value of `l` -> `List reference`; + access `l` -> `List reference`; call `get` on `List reference` with arguments (`int 0`) -> `def`; - implicit cast value of `def` to value of `int 1` -> `int 1`; - assign value of `int 1` to `i`; + implicit cast `def` to `int 1` -> `int 1`; + assign `int 1` to `i`; (note internally `int 1` is unboxed from `Integer 1` when read from a `def` type value) + @@ -436,11 +421,15 @@ respective reference type values and vice versa. Promotion is when a value is converted into either a certain type or when multiple values are converted into equivalent types for use during an -<>. Each <> that -requires promotion will have a promotion table that shows all allowed -conversions. Values can be promoted to the `def` type at compile-time; however, -at run-time, the promoted type of value is derived from what the `def` type -value represents. +<>. Each operation that requires promotion will +have a promotion table that shows all allowed conversions. Values can be +promoted to the `def` type at compile-time; however, at run-time, the promoted +type value is derived from what the `def` type value represents. + +*Errors* + +* If a specific operation cannot find an allowed promotion type for the type(s) + of value(s) given. *Examples* @@ -453,20 +442,19 @@ value represents. <3> float f = x + 2.0F; ---- <1> declare `double d`; - promote value of `int 2` and value of `double 2.0 @0` -> `double 2.0 @0`; - implicit cast value of `int 2` to value of `double 2.0 @1` - -> `double 2.0 @1`; + promote `int 2` and `double 2.0 @0` -> `double 2.0 @0`; + implicit cast `int 2` to `double 2.0 @1` -> `double 2.0 @1`; add `double 2.0 @1` and `double 2.0 @0` -> `double 4.0`; - assign value of `double 4.0` to `d` + assign `double 4.0` to `d` <2> declare `def x`; - implicit cast value of `int 1` to value of `def` -> `def`; - assign value of `def` to `x`; + implicit cast `int 1` to `def` -> `def`; + assign `def` to `x`; <3> declare `float f`; - access value of `x` -> `def`; - implicit cast value of `def` to value of `int 1` -> `int 1`; - promote value of `int 1` and value of `float 2.0` -> `float 2.0`; - implicit cast value of `int 1` to value of `float 1.0` -> `float `1.0`; + access `x` -> `def`; + implicit cast `def` to `int 1` -> `int 1`; + promote `int 1` and `float 2.0` -> `float 2.0`; + implicit cast `int 1` to `float 1.0` -> `float `1.0`; add `float 1.0` and `float 2.0` -> `float 3.0`; - assign value of `float 3.0` to `f`; + assign `float 3.0` to `f`; (note this example illustrates promotion done at run-time as promotion - done at compile-time would have resolved to a `def` type value) \ No newline at end of file + done at compile-time would have resolved to a `def` type value) \ No newline at end of file From b95ce254fc16272abc8114ddf13978b08f9bad27 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Mon, 21 May 2018 10:49:51 -0700 Subject: [PATCH 23/27] More changes. --- docs/painless/painless-casting.asciidoc | 12 ++++++------ docs/painless/painless-types.asciidoc | 15 +++++++-------- 2 files changed, 13 insertions(+), 14 deletions(-) diff --git a/docs/painless/painless-casting.asciidoc b/docs/painless/painless-casting.asciidoc index d72d12b8f7ee7..92dab330899f3 100644 --- a/docs/painless/painless-casting.asciidoc +++ b/docs/painless/painless-casting.asciidoc @@ -419,12 +419,12 @@ values and vice versa. [[promotion]] ==== Promotion -Promotion is when a value is converted into either a certain type or when -multiple values are converted into equivalent types for use during an -<>. Each operation that requires promotion will -have a promotion table that shows all allowed conversions. Values can be -promoted to the `def` type at compile-time; however, at run-time, the promoted -type value is derived from what the `def` type value represents. +Promotion is when a single value is or multiple values are converted to a +certain type for use during an <>. Each operation +that requires promotion has a promotion table that shows all allowed +conversions. Values can be promoted to the `def` type at compile-time; however, +at run-time, the promoted type value is derived from what the `def` type value +represents. *Errors* diff --git a/docs/painless/painless-types.asciidoc b/docs/painless/painless-types.asciidoc index 7aa8052482a0b..841125ff54178 100644 --- a/docs/painless/painless-types.asciidoc +++ b/docs/painless/painless-types.asciidoc @@ -11,19 +11,18 @@ categories: <>, [[primitive-types]] ==== Primitive Types -Primitive types are built straight into the JVM, directly contain their data, +Primitive types are built into the JVM natively, directly contain their data, and are allocated to non-heap memory. Primitive type values are copied when <> and when passed into a <> or function as arguments. Primitive types have corresponding <> (also known as <>). Any member of the corresponding -<> can be <> or -<> by executing the appropriate operation on the -primitive type value. Operations performed in this manner convert -(<>) the primitive type value to its corresponding -<> value at runtime and execute the specified -<> or <>. +reference type can be <> or <> by +executing the appropriate operation on the primitive type value. Operations +performed in this manner box the primitive type value to its corresponding +reference type value at runtime and execute the specified field access or +method call. The following primitive types are available: @@ -93,7 +92,7 @@ logical quantity with two possible values of `true` and `false` assign value of `boolean true` to `b` + * Method call on a primitive type from the corresponding -<>. +< Date: Mon, 21 May 2018 14:24:51 -0700 Subject: [PATCH 24/27] More fixes. --- docs/painless/painless-casting.asciidoc | 30 ++-- docs/painless/painless-types.asciidoc | 181 ++++++++++++------------ 2 files changed, 105 insertions(+), 106 deletions(-) diff --git a/docs/painless/painless-casting.asciidoc b/docs/painless/painless-casting.asciidoc index 92dab330899f3..c5f874611a32e 100644 --- a/docs/painless/painless-casting.asciidoc +++ b/docs/painless/painless-casting.asciidoc @@ -5,7 +5,7 @@ A cast converts the value of an original <> to the equivalent value of a target <>. An implicit cast infers the target type and automatically occurs during certain <>. An explicit cast specifies the target type -and forcefully occurs as its own operation. Use the *cast operator ()* to +and forcefully occurs as its own operation. Use the *cast operator* to specify an explicit cast. *Errors* @@ -297,7 +297,7 @@ based on the current type value the `def` type value represents. [[string-character-casting]] ==== String to Character Casting -Use the <> to convert a +Use the <> to convert a <> value into a <> value. *Errors* @@ -345,18 +345,18 @@ reference type to its corresponding primitive type. Implicit boxing/unboxing occurs during the following <>: -* Conversions between the <> and - primitive types will be implicitly boxed/unboxed as +* Conversions between a <> and + a primitive type will be implicitly boxed/unboxed as necessary, though this is referred to as an implicit cast throughout the documentation. * <>/function call arguments will be implicitly boxed/unboxed as necessary. -* Primitive type values will be implicitly boxed when a reference type method - call is invoked on a primitive type value. +* A primitive type value will be implicitly boxed when a reference type method + call is invoked on it. Explicit boxing/unboxing is not allowed. Use the reference type API to -explicitly convert primitive type values to their respective reference type -values and vice versa. +explicitly convert a primitive type value to its respective reference type +value and vice versa. *Errors* @@ -419,12 +419,14 @@ values and vice versa. [[promotion]] ==== Promotion -Promotion is when a single value is or multiple values are converted to a -certain type for use during an <>. Each operation -that requires promotion has a promotion table that shows all allowed -conversions. Values can be promoted to the `def` type at compile-time; however, -at run-time, the promoted type value is derived from what the `def` type value -represents. +Promotion is when a single value is implicitly <> to a +certain type or multiple values are implicitly <> to the +same type as required for evaluation by certain +<>. 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 can be promoted to a `def` type at compile-time; however, the +promoted type value is derived from what the `def` type value represents at +run-time. *Errors* diff --git a/docs/painless/painless-types.asciidoc b/docs/painless/painless-types.asciidoc index 841125ff54178..99862a71c01bb 100644 --- a/docs/painless/painless-types.asciidoc +++ b/docs/painless/painless-types.asciidoc @@ -1,27 +1,28 @@ [[painless-types]] === Types -Types are a classification of data used to describe the properties of values -operated on in expressions and statements. These properties describe what data -the value can represent such as a number, string, or something more complex and -the rules for when a value is operated on. Types are split into the following -categories: <>, -<>, and <>. +A type is a classification of data used to define the properties of a value. +These properties specify what data a value represents such as a number, string, +These properties specify what data a value represents such as a number, string, +or something more complex and the rules for when a value is evaluated during +an <>. Each type belongs to one of the following +categories: <>, <>, +or <>. [[primitive-types]] ==== Primitive Types -Primitive types are built into the JVM natively, directly contain their data, -and are allocated to non-heap memory. Primitive type values are copied when +A primitive type represents basic data build natively into the JVM and is +allocated to non-heap memory. A primitive type value is copied when <> and when passed into a <> or -function as arguments. +function as an argument. -Primitive types have corresponding <> (also -known as <>). Any member of the corresponding +A primitive type has a corresponding <> (also +known as a <>). Any member of the corresponding reference type can be <> or <> by -executing the appropriate operation on the primitive type value. Operations +evaluating the appropriate operation on a primitive type value. Operations performed in this manner box the primitive type value to its corresponding -reference type value at runtime and execute the specified field access or +reference type value at runtime and evaluate the specified field access or method call. The following primitive types are available: @@ -85,14 +86,13 @@ logical quantity with two possible values of `true` and `false` ---- + <1> declare `int i`; - assign value of `int 1` to `i` + assign `int 1` to `i` <2> declare `double d`; - assign default value of `double 0.0` to `d` + assign default `double 0.0` to `d` <3> declare `boolean b`; - assign value of `boolean true` to `b` + assign `boolean true` to `b` + -* Method call on a primitive type from the corresponding -< declare `int i`; - assign value of `int 1` to `i` -<2> access value of `i` -> `int 1`; - box value of `int 1` -> `Integer 1 reference`; + assign `int 1` to `i` +<2> access `i` -> `int 1`; + box `int 1` -> `Integer 1 reference`; call `toString` on `Integer 1 reference` -> `String '1'` [[reference-types]] ==== Reference Types -Reference types are named constructs (objects), potentially representing +A reference type is a named construct (object), potentially representing multiple pieces of data (member fields) and logic to manipulate that data (member methods), defined as part of the application programming interface -(API) for use in scripts. +(API). A reference type instance is a single set of data for one reference type object allocated to the heap. A reference type instance is allocated using the -<>. Use reference type instances to store -and manipulate complex data. +<>. Use a reference type instance to +store and manipulate complex data. -Reference type values refer to reference type instances, and multiple reference -type values may refer to a single reference type instance. A change to a -reference type instance will affect all reference type values referring to that -instance. Reference type values are shallow-copied when +A reference type value refers to a reference type instance, and multiple +reference type values may refer to a single reference type instance. A change to +a reference type instance will affect all reference type values referring to +that specific instance. A reference type value is shallow-copied when <> and when passed into a <> or -function as arguments. +function as an argument. The default value for a <> reference type <> is `null`. <> a <> reference type instance or an existing reference type value to a reference type <> for -<> within a script. <> `null` to a -reference type <> to indicate the reference type -value refers to no reference type instance. The JVM will garbage collect a -reference type instance when no reference type values refer to that reference -type instance. - -A reference type object specifies zero-to-many of each of the following: - -static member fields:: - -Static member fields are named and <> pieces of data -specific to a single reference type object. Each reference type *object* -contains one set of data representative of its static member fields. Use the -<> in correspondence with the reference type -object name to access static member fields for reading and writing to a -specific reference type *object*. No reference type instance allocation is -necessary to use static member fields. - -non-static member fields:: - -Non-static member fields are named and <> pieces of data -specified by a reference type object. Each reference type *instance* contains -one set of data representative of its reference type object's non-static member -fields. Use the <> for reading and writing to -non-static member fields of a specific reference type *instance*. An allocated -reference type instance is required to use non-static member fields. - -static member methods:: - -Static member methods are functions specific to a single reference type -*object*. Use the <> in -correspondence with the reference type object name to invoke static member -methods. No reference type instance allocation is necessary to use static -member methods. - -non-static member methods:: - -Non-static member methods are functions specified by a reference type object -and called on a specific reference type *instance*. Non-static member methods -called on a specific reference type instance may read from and write to -non-static member fields of that specific reference type instance. Use the -<> in correspondence with a -specific reference type instance to invoke non-static member methods. An -allocated reference type instance is required to use non-static member methods. - -constructors:: - -Constructors are a special type of function specific to a reference type -*object* used to allocate reference type instances of that reference type -object. Use the <> to -allocate a reference type instance. - -Reference type objects support a basic inheritance model. Consider types A and +evaluation during a later <>. +<> `null` to a reference type +<> to indicate the reference type value refers to +no reference type instance. The JVM will garbage collect a reference type +instance when it is no longer referred to by any reference types values. + +A reference type object defines zero-to-many of each of the following: + +static member field:: + +A static member field is a named and <> piece of data. +Each reference type *object* contains one set of data representative of its +static member fields. Use the <> in +correspondence with the reference type object name to access a static member +field for reading and writing to a specific reference type *object*. No +reference type instance allocation is necessary to use a static member field. + +non-static member field:: + +A non-static member field is a named and <> piece of +data. Each reference type *instance* contains one set of data representative of +its reference type object's non-static member fields. Use the +<> for reading and writing to a +non-static member field of a specific reference type *instance*. An allocated +reference type instance is required to use a non-static member field. + +static member method:: + +A static member method is a function called on a reference type *object*. Use +the <> in correspondence with the +reference type object name to call a static member method. No reference type +instance allocation is necessary to use a static member method. + +non-static member method:: + +A non-static member method is a function called on a reference type *instance*. +A non-static member method called on a reference type instance can read from and +write to non-static member fields of that specific reference type instance. Use +the <> in correspondence with a specific +reference type instance to call a non-static member method. An allocated +reference type instance is required to use a non-static member method. + +constructor:: + +A constructor is a special type of function used to allocate a reference type +*instance* defined by a specific reference type *object*. Use the +<> to allocate a reference type +instance. + +A reference type object follows a basic inheritance model. Consider types A and B. Type A is considered to be a parent of B, and B a child of A, if B inherits (is able to access as its own) all of A's non-static members. Type B is considered a descendant of A if there exists a recursive parent-child @@ -193,7 +190,7 @@ relationships. *Examples* -* Reference types used in several different <>. +* Reference types evaluated in several different operations. + [source,Painless] ---- @@ -204,18 +201,18 @@ relationships. + <1> declare `List l`; allocate `ArrayList` instance -> `ArrayList reference`; - implicit cast value of `ArrayList reference` to value of `List reference` + implicit cast `ArrayList reference` to `List reference` -> `List reference`; - assign value of `List reference` to `l` -<2> access value of `l` -> `List reference`; - implicit cast value of `int 1` to value of `def` -> `def` + assign `List reference` to `l` +<2> access `l` -> `List reference`; + implicit cast `int 1` to `def` -> `def` call `add` on `List reference` with arguments (`def`) <3> declare `int i`; - access value of `l` -> `List reference`; + access `l` -> `List reference`; call `get` on `List reference` with arguments (`int 0`) -> `def`; - implicit cast value of `def` to value of `int 1` -> `int 1`; - add value of `int 1` and value of `int 2` -> `int 3`; - assign value of `int 3` to `i` + implicit cast `def` to `int 1` -> `int 1`; + add `int 1` and `int 2` -> `int 3`; + assign `int 3` to `i` + * Sharing a reference type instance. + From 8fc45660cc7c89088d91806db28b9cd5e3460fb7 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Mon, 21 May 2018 17:19:16 -0700 Subject: [PATCH 25/27] Fixed casting and types based on PR feedback. --- docs/painless/painless-casting.asciidoc | 48 ++-- docs/painless/painless-operators.asciidoc | 1 + docs/painless/painless-types.asciidoc | 320 +++++++++++----------- 3 files changed, 181 insertions(+), 188 deletions(-) diff --git a/docs/painless/painless-casting.asciidoc b/docs/painless/painless-casting.asciidoc index c5f874611a32e..5817f9bcb9b57 100644 --- a/docs/painless/painless-casting.asciidoc +++ b/docs/painless/painless-casting.asciidoc @@ -1,12 +1,11 @@ [[painless-casting]] === Casting -A cast converts the value of an original <> to the -equivalent value of a target <>. An implicit cast infers -the target type and automatically occurs during certain -<>. An explicit cast specifies the target type -and forcefully occurs as its own operation. Use the *cast operator* to -specify an explicit cast. +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 certain <>. An explicit cast specifies +the target type and forcefully occurs as its own operation. Use the *cast +operator* to specify an explicit cast. *Errors* @@ -52,8 +51,8 @@ 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 is shown as a row in the table -below. +The allowed casts for values of each numeric type are shown as a row in the +following table: |==== | | byte | short | char | int | long | float | double @@ -297,8 +296,8 @@ based on the current type value the `def` type value represents. [[string-character-casting]] ==== String to Character Casting -Use the <> to convert a -<> value into a <> value. +Use the *cast operator* to convert a <> value into a +<> value. *Errors* @@ -306,7 +305,7 @@ Use the <> to convert a *Examples* -* Casting <> into char type values. +* Casting strings, string literals into char type values. + [source,Painless] ---- @@ -337,20 +336,17 @@ Use the <> to convert a [[boxing-unboxing]] ==== Boxing and Unboxing -Boxing is a special type of cast used to convert a -<> to its corresponding -<>. Unboxing is the reverse used to convert a +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 -<>: +Implicit boxing/unboxing occurs during the following operations: -* Conversions between a <> and +* Conversions between a `def` type and a primitive type will be implicitly boxed/unboxed as necessary, though this is referred to as an implicit cast throughout the documentation. -* <>/function call arguments will be implicitly - boxed/unboxed as necessary. +* Method/function call arguments will be implicitly boxed/unboxed as necessary. * A primitive type value will be implicitly boxed when a reference type method call is invoked on it. @@ -419,14 +415,12 @@ value and vice versa. [[promotion]] ==== Promotion -Promotion is when a single value is implicitly <> to a -certain type or multiple values are implicitly <> to the -same type as required for evaluation by certain -<>. 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 can be promoted to a `def` type at compile-time; however, the -promoted type value is derived from what the `def` type value represents at -run-time. +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 can be promoted to a `def` type at compile-time; however, the promoted +type value is derived from what the `def` type value represents at run-time. *Errors* diff --git a/docs/painless/painless-operators.asciidoc b/docs/painless/painless-operators.asciidoc index d80a6699680e0..8329686f663af 100644 --- a/docs/painless/painless-operators.asciidoc +++ b/docs/painless/painless-operators.asciidoc @@ -339,6 +339,7 @@ return d[z]; // Access the 1st element of array d using the NOTE: The use of the `def` type in the second example means that the types cannot be resolved until runtime. +[[array-length]] ===== Array Length Arrays contain a special member known as 'length' that is a read-only value that contains the size of the array. This member can be accessed from an array using the dot operator. diff --git a/docs/painless/painless-types.asciidoc b/docs/painless/painless-types.asciidoc index 99862a71c01bb..2ec87c8806414 100644 --- a/docs/painless/painless-types.asciidoc +++ b/docs/painless/painless-types.asciidoc @@ -2,28 +2,26 @@ === Types A type is a classification of data used to define the properties of a value. -These properties specify what data a value represents such as a number, string, -These properties specify what data a value represents such as a number, string, -or something more complex and the rules for when a value is evaluated during -an <>. Each type belongs to one of the following -categories: <>, <>, -or <>. +These properties specify what data a value represents and the rules for how a +value is evaluated during an <>. Each type +belongs to one of the following categories: <>, +<>, or <>. [[primitive-types]] ==== Primitive Types A primitive type represents basic data build natively into the JVM and is -allocated to non-heap memory. A primitive type value is copied when -<> and when passed into a <> or -function as an argument. - -A primitive type has a corresponding <> (also -known as a <>). Any member of the corresponding -reference type can be <> or <> by -evaluating the appropriate operation on a primitive type value. Operations -performed in this manner box the primitive type value to its corresponding -reference type value at runtime and evaluate the specified field access or -method call. +allocated to non-heap memory. Declare a primitive type +<>, and assign it a primitive type value for +evaluation during later operations. The default value for a newly-declared +primitive type variable is listed as part of the definitions below. A primitive +type value is copied during an assignment or as an argument for a +method/function call. + +A primitive type has a corresponding reference type (also known as a boxed +type). Use the <> or +<> on a primitive type value to force +evaluation as its corresponding reference type value. The following primitive types are available: @@ -75,8 +73,7 @@ logical quantity with two possible values of `true` and `false` *Examples* -* Primitive types used in <> and -<>. +* Primitive types used in declaration, declaration and assignment. + [source,Painless] ---- @@ -86,11 +83,11 @@ logical quantity with two possible values of `true` and `false` ---- + <1> declare `int i`; - assign `int 1` to `i` + assign `int 1` to `i` <2> declare `double d`; - assign default `double 0.0` to `d` + assign default `double 0.0` to `d` <3> declare `boolean b`; - assign `boolean true` to `b` + assign `boolean true` to `b` + * Method call on a primitive type using the corresponding reference type. + @@ -101,9 +98,9 @@ logical quantity with two possible values of `true` and `false` ---- + <1> declare `int i`; - assign `int 1` to `i` -<2> access `i` -> `int 1`; - box `int 1` -> `Integer 1 reference`; + assign `int 1` to `i` +<2> access `i` -> `int 1`; + box `int 1` -> `Integer 1 reference`; call `toString` on `Integer 1 reference` -> `String '1'` [[reference-types]] @@ -112,63 +109,62 @@ logical quantity with two possible values of `true` and `false` A reference type is a named construct (object), potentially representing multiple pieces of data (member fields) and logic to manipulate that data (member methods), defined as part of the application programming interface -(API). +(API) for scripts. A reference type instance is a single set of data for one reference type -object allocated to the heap. A reference type instance is allocated using the -<>. Use a reference type instance to -store and manipulate complex data. +object allocated to the heap. Use the +<> to allocate a reference type +instance. Use a reference type instance to read from, write to, and manipulate +complex data. A reference type value refers to a reference type instance, and multiple -reference type values may refer to a single reference type instance. A change to +reference type values may refer to the same reference type instance. A change to a reference type instance will affect all reference type values referring to -that specific instance. A reference type value is shallow-copied when -<> and when passed into a <> or -function as an argument. - -The default value for a <> reference type -<> is `null`. <> a -<> reference type instance or an existing -reference type value to a reference type <> for -evaluation during a later <>. -<> `null` to a reference type -<> to indicate the reference type value refers to -no reference type instance. The JVM will garbage collect a reference type -instance when it is no longer referred to by any reference types values. +that specific instance. + +Declare a reference type <>, and assign it a +reference type value for evaluation during later operations. The default value +for a newly-declared reference type variable is `null`. A reference type value +is shallow-copied during an assignment or as an argument for a method/function +call. Assign `null` to a reference type variable to indicate the reference type +value refers to no reference type instance. The JVM will garbage collect a +reference type instance when it is no longer referred to by any reference type +values. Pass `null` as an argument to a method/function call to indicate the +argument refers to no reference type instance. A reference type object defines zero-to-many of each of the following: static member field:: -A static member field is a named and <> piece of data. -Each reference type *object* contains one set of data representative of its -static member fields. Use the <> in -correspondence with the reference type object name to access a static member -field for reading and writing to a specific reference type *object*. No -reference type instance allocation is necessary to use a static member field. +A static member field is a named and typed piece of data. Each reference type +*object* contains one set of data representative of its static member fields. +Use the <> in correspondence with the +reference type object name to access a static member field for reading and +writing to a specific reference type *object*. No reference type instance +allocation is necessary to use a static member field. non-static member field:: -A non-static member field is a named and <> piece of -data. Each reference type *instance* contains one set of data representative of -its reference type object's non-static member fields. Use the -<> for reading and writing to a -non-static member field of a specific reference type *instance*. An allocated -reference type instance is required to use a non-static member field. +A non-static member field is a named and typed piece of data. Each reference +type *instance* contains one set of data representative of its reference type +object's non-static member fields. Use the +<> for reading and writing to a non-static +member field of a specific reference type *instance*. An allocated reference +type instance is required to use a non-static member field. static member method:: A static member method is a function called on a reference type *object*. Use -the <> in correspondence with the -reference type object name to call a static member method. No reference type -instance allocation is necessary to use a static member method. +the <> in correspondence with the reference +type object name to call a static member method. No reference type instance +allocation is necessary to use a static member method. non-static member method:: A non-static member method is a function called on a reference type *instance*. A non-static member method called on a reference type instance can read from and write to non-static member fields of that specific reference type instance. Use -the <> in correspondence with a specific +the <> in correspondence with a specific reference type instance to call a non-static member method. An allocated reference type instance is required to use a non-static member method. @@ -176,7 +172,7 @@ constructor:: A constructor is a special type of function used to allocate a reference type *instance* defined by a specific reference type *object*. Use the -<> to allocate a reference type +<> to allocate a reference type instance. A reference type object follows a basic inheritance model. Consider types A and @@ -201,18 +197,17 @@ relationships. + <1> declare `List l`; allocate `ArrayList` instance -> `ArrayList reference`; - implicit cast `ArrayList reference` to `List reference` - -> `List reference`; - assign `List reference` to `l` -<2> access `l` -> `List reference`; - implicit cast `int 1` to `def` -> `def` + implicit cast `ArrayList reference` to `List reference` -> `List reference`; + assign `List reference` to `l` +<2> access `l` -> `List reference`; + implicit cast `int 1` to `def` -> `def` call `add` on `List reference` with arguments (`def`) <3> declare `int i`; - access `l` -> `List reference`; + access `l` -> `List reference`; call `get` on `List reference` with arguments (`int 0`) -> `def`; - implicit cast `def` to `int 1` -> `int 1`; - add `int 1` and `int 2` -> `int 3`; - assign `int 3` to `i` + implicit cast `def` to `int 1` -> `int 1`; + add `int 1` and `int 2` -> `int 3`; + assign `int 3` to `i` + * Sharing a reference type instance. + @@ -227,28 +222,27 @@ relationships. + <1> declare `List l0`; allocate `ArrayList` instance -> `ArrayList reference`; - implicit cast value of `ArrayList reference` to value of `List reference` - -> `List reference`; - assign value of `List reference` to `l0` + implicit cast `ArrayList reference` to `List reference` -> `List reference`; + assign `List reference` to `l0` <2> declare `List l1`; - access value of `l0` -> `List reference`; - assign value of `List reference` to `l1` + access `l0` -> `List reference`; + assign `List reference` to `l1` (note `l0` and `l1` refer to the same instance known as a shallow-copy) -<3> access value of `l0` -> `List reference`; - implicit cast value of `int 1` to value of `def` -> `def` +<3> access `l0` -> `List reference`; + implicit cast `int 1` to `def` -> `def` call `add` on `List reference` with arguments (`def`) -<4> access value of `l1` -> `List reference`; - implicit cast value of `int 2` to value of `def` -> `def` +<4> access `l1` -> `List reference`; + implicit cast `int 2` to `def` -> `def` call `add` on `List reference` with arguments (`def`) <5> declare `int i`; - access value of `l0` -> `List reference`; + access `l0` -> `List reference`; call `get` on `List reference` with arguments (`int 0`) -> `def @0`; - implicit cast value of `def @0` to value of `int 1` -> `int 1`; - access value of `l1` -> `List reference`; + implicit cast `def @0` to `int 1` -> `int 1`; + access `l1` -> `List reference`; call `get` on `List reference` with arguments (`int 1`) -> `def @1`; - implicit cast value of `def @1` to value of `int 2` -> `int 2`; - add value of `int 1` and value of `int 2` -> `int 3`; - assign value of `int 3` to `i`; + implicit cast `def @1` to `int 2` -> `int 2`; + add `int 1` and `int 2` -> `int 3`; + assign `int 3` to `i`; + * Using the static members of a reference type. + @@ -259,35 +253,34 @@ relationships. ---- + <1> declare `int i`; - access value of `MAX_VALUE` on `Integer` -> `int 2147483647`; - assign value of `int 2147483647` to `i` + access `MAX_VALUE` on `Integer` -> `int 2147483647`; + assign `int 2147483647` to `i` <2> declare `long l`; call `parseLong` on `Long` with arguments (`long 123`) -> `long 123`; - assign value of `long 123` to `l` + assign `long 123` to `l` [[dynamic-types]] ==== Dynamic Types -Use dynamic type values to represent the values of any primitive type or -reference type under a single type name `def`. A `def` type value mimics -the behavior of whatever value it currently represents and will always -represent the child-most descendant type value of any value when used in -<> and statements. +A dynamic type value can represent the value of any primitive type or +reference type using a single type name `def`. A `def` type value mimics +the behavior of whatever value it represents at run-time and will always +represent the child-most descendant type value of any type value when evaluated +during operations. -Internally, if a `def` type value is a primitive type value, the value is -converted (<>) to the corresponding reference type -instance. However, the `def` type still behaves like the primitive type -including within the <>. +Declare a `def` type <>, and assign it +any type of value for evaluation during later operations. The default value +for a newly-declared `def` type variable is `null`. A `def` type variable or +method/function parameter can change the type it represents during the +compilation and evaluation of a script. -The default value for a <> `def` type -<> is `null`. A `def` type -<> can have different types -<> throughout a script. +Using the `def` type can have a slight impact on performance. Use only primitive +types and reference types directly when performance is critical. -<> using the `def` type will generate -errors at runtime if an inappropriate type is represented. Using the `def` -type can have a slight impact on performance. Use only primitive types and -reference types directly when performance is critical. +*Errors* + +* If a `def` type value represents an inappropriate type for evaluation of an + operation at run-time. *Examples* @@ -301,14 +294,14 @@ reference types directly when performance is critical. ---- + <1> declare `def dp`; - implicit cast value of `int 1` to value of `def` -> `def`; - assign value of `def` to `dp` + implicit cast `int 1` to `def` -> `def`; + assign `def` to `dp` <2> declare `def dr`; allocate `ArrayList` instance -> `ArrayList reference`; - implicit cast value of `ArrayList reference` to value of `def` -> `def`; - assign value of `def` to `dr` -<3> access value of `dp` -> `def`; - assign value of `def` to `dr`; + implicit cast `ArrayList reference` to `def` -> `def`; + assign `def` to `dr` +<3> access `dp` -> `def`; + assign `def` to `dr`; (note the switch in the type `dr` represents from `ArrayList` to `int`) + * A `def` type value representing the child-most descendant of a value. @@ -322,18 +315,17 @@ reference types directly when performance is critical. + <1> declare `Object l`; allocate `ArrayList` instance -> `ArrayList reference`; - implicit cast value of `ArrayList reference` to value of `Object reference` + implicit cast `ArrayList reference` to `Object reference` -> `Object reference`; - assign value of `Object reference` to `l` + assign `Object reference` to `l` <2> declare `def d`; - access value of `l` -> `Object reference`; - implicit cast value of `Object reference` to value of `def` -> `def`; - assign value of `def` to `d`; -<3> access value of `d` -> `def`; - implicit cast value of `def` to value of `ArrayList reference` - -> `ArrayList reference`; + access `l` -> `Object reference`; + implicit cast `Object reference` to `def` -> `def`; + assign `def` to `d`; +<3> access `d` -> `def`; + implicit cast `def` to `ArrayList reference` -> `ArrayList reference`; call `ensureCapacity` on `ArrayList reference` with arguments (`int 10`); - (note value of `def` was implicit cast to value of `ArrayList reference` + (note `def` was implicit cast to `ArrayList reference` since ArrayList` is the child-most descendant type value that the `def` type value represents) @@ -341,10 +333,10 @@ reference types directly when performance is critical. ==== String Type The `String` type is a specialized reference type that does not require -explicit allocation. Use <> to directly -<> or <> on `String` values. -While not required, the <> can allocate -`String` values. +explicit allocation. Use a <> to directly evaluate a +`String` type value. While not required, +the <> can allocate `String` type +instances. *Examples* @@ -359,21 +351,21 @@ While not required, the <> can allocate ---- + <1> declare `String r`; - assign value of `String "some text"` to `r` + assign `String "some text"` to `r` <2> declare `String s`; - assign value of `String 'some text'` to `s` + assign `String 'some text'` to `s` <3> declare `String t`; allocate `String` instance with arguments (`String "some text"`) -> `String "some text"`; - assign value of `String "some text"` to `t` + assign `String "some text"` to `t` <4> declare `String u`; - assign default value of `null` to `u` + assign default `null` to `u` [[void-type]] ==== void Type -The `void` type represents the concept of a lack of type. The `void` type is -primarily used to indicate a function will return no value. +The `void` type represents the concept of a lack of type. Use the `void` type to +indicate a function returns no value. *Examples* @@ -389,21 +381,28 @@ void addToList(List l, def d) { [[array-type]] ==== Array Type -The array type is a specialized reference type where an array type instance -represents a series of values. All values in an array type instance are of -the same type. Each value is assigned an index from within the range -`[0, length)` where length is the total number of values allocated for the -array type instance. Specify the type of values and the length during an -array allocation. - -Allocate an array type instance using the <> or the -<>. Array type instances are -allocated to the heap. <> and <> -array type variables for <> within scripts. The -default value for newly-declared array instance types is `null`. Array type -values are shallow-copied when <> and when passed into a -<> or function as arguments. Read and write to individual -values within the array type instance using the <>. +An array type is a specialized reference type where an array type instance +represents a series of values allocated to the heap. All values in an array +type instance are of the same type. Each value is assigned an index from within +the range `[0, length)` where length is the total number of values allocated for +the array type instance. + +Use the <> or the +<> to allocate an array +type instance. Declare an array type <>, and +assign it an array type value for evaluation during later operations. The +default value for a newly-declared array type variable is `null`. An array type +value is shallow-copied during an assignment or as an argument for a +method/function call. Assign `null` to an array type variable to indicate the +array type value refers to no array type instance. The JVM will garbage collect +an array type instance when it is no longer referred to by any array type +values. Pass `null` as an argument to a method/function call to indicate the +argument refers to no array type instance. + +Use the <> to retrieve the length of an +array type value as an int type value. Use the +<> to read and write to individual values +within an array type value. When an array type instance is allocated with multiple dimensions using the range `[2, d]` where `d >= 2`, each dimension in the range `[1, d-1]` is also @@ -427,25 +426,24 @@ the array type `int[][]`. ---- + <1> declare `int[] x`; - assign default value of `null` to `x` + assign default `null` to `x` <2> declare `float[] y`; allocate `1-d float array` instance with `length [10]` -> `1-d float array reference`; - assign value of `1-d float array reference` to `y` + assign `1-d float array reference` to `y` <3> declare `def z`; allocate `1-d float array` instance with `length [5]` -> `1-d float array reference`; - implicit cast value of `1-d float array reference` to value of `def` - -> `def`; - assign value of `def` to `z` -<4> access value of `y` -> `1-d float array reference`; - assign value of `float 1.0` to `index [9]` of `1-d float array reference` -<5> access value of `y` -> `1-d float array reference @0`; + implicit cast `1-d float array reference` to `def` -> `def`; + assign `def` to `z` +<4> access `y` -> `1-d float array reference`; + assign `float 1.0` to `index [9]` of `1-d float array reference` +<5> access `y` -> `1-d float array reference @0`; access `index [9]` of `1-d float array reference @0` -> `float 1.0`; - access value of `z` -> `def`; - implicit cast value of `def` to value of `1-d float array reference @1` + access `z` -> `def`; + implicit cast `def` to `1-d float array reference @1` -> `1-d float array reference @1`; - assign value of `float 1.0` to `index [0]` of `1-d float array reference @1` + assign `float 1.0` to `index [0]` of `1-d float array reference @1` + * Use of a multi-dimensional array. + @@ -459,10 +457,10 @@ the array type `int[][]`. <1> declare `int[][][] ia`; allocate `3-d int array` instance with length `[2, 3, 4]` -> `3-d int array reference`; - assign value of `3-d int array reference` to `ia3` -<2> access value of `ia3` -> `3-d int array reference`; - assign value of `int 99` to `index [1, 2, 3]` of `3-d int array reference` + assign `3-d int array reference` to `ia3` +<2> access `ia3` -> `3-d int array reference`; + assign `int 99` to `index [1, 2, 3]` of `3-d int array reference` <3> declare `int i`; - access value of `ia3` -> `3-d int array reference`; - access value of `index [1, 2, 3]` of `3-d int array reference` -> `int 99`; - assign value of `int 99` to `i` \ No newline at end of file + access `ia3` -> `3-d int array reference`; + access `index [1, 2, 3]` of `3-d int array reference` -> `int 99`; + assign `int 99` to `i` \ No newline at end of file From ca2bb83c767bb056a314086796f3bbc0f47dd66b Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Mon, 21 May 2018 18:41:31 -0700 Subject: [PATCH 26/27] Cleaned up more. --- docs/painless/painless-casting.asciidoc | 22 ++-- docs/painless/painless-comments.asciidoc | 12 +- docs/painless/painless-identifiers.asciidoc | 8 +- docs/painless/painless-keywords.asciidoc | 6 +- docs/painless/painless-lang-spec.asciidoc | 2 +- docs/painless/painless-literals.asciidoc | 32 ++--- docs/painless/painless-types.asciidoc | 22 ++-- docs/painless/painless-variables.asciidoc | 135 ++++++++++---------- 8 files changed, 118 insertions(+), 121 deletions(-) diff --git a/docs/painless/painless-casting.asciidoc b/docs/painless/painless-casting.asciidoc index 5817f9bcb9b57..430b45eb0dd55 100644 --- a/docs/painless/painless-casting.asciidoc +++ b/docs/painless/painless-casting.asciidoc @@ -296,16 +296,17 @@ based on the current type value the `def` type value represents. [[string-character-casting]] ==== String to Character Casting -Use the *cast operator* to convert a <> value into a -<> value. +Use the *cast operator* to convert a <> value into a +<> value. *Errors* -* If the String type value isn't one character in length. +* If the `String` type value isn't one character in length. +* If the `String` type value is `null`. *Examples* -* Casting strings, string literals into char type values. +* Casting string literals into `char` type values. + [source,Painless] ---- @@ -319,7 +320,7 @@ Use the *cast operator* to convert a <> value into a <2> explicit cast `String 'c'` to `char c` -> `char c`; assign `char c` to `c` + -* Casting a String type value into a char type value. +* Casting a `String` reference into a `char` value. + [source,Painless] ---- @@ -342,10 +343,9 @@ reference type to its corresponding primitive type. Implicit boxing/unboxing occurs during the following operations: -* Conversions between a `def` type and - a primitive type will be implicitly boxed/unboxed as - necessary, though this is referred to as an implicit cast throughout the - documentation. +* Conversions between a `def` type and a primitive type will be implicitly + boxed/unboxed as necessary, though this is referred to as an implicit cast + throughout the documentation. * Method/function call arguments will be implicitly boxed/unboxed as necessary. * A primitive type value will be implicitly boxed when a reference type method call is invoked on it. @@ -388,8 +388,8 @@ value and vice versa. call `get` on `List reference` with arguments (`int 0`) -> `def`; implicit cast `def` to `int 1` -> `int 1`; assign `int 1` to `i`; - (note internally `int 1` is unboxed from `Integer 1` when read from a `def` - type value) + (note internally `int 1` is unboxed from `Integer 1` when loaded from a + `def` type value) + * Uses of invalid boxing/unboxing resulting in errors. + diff --git a/docs/painless/painless-comments.asciidoc b/docs/painless/painless-comments.asciidoc index 588e464d97f78..bde30e37e04e1 100644 --- a/docs/painless/painless-comments.asciidoc +++ b/docs/painless/painless-comments.asciidoc @@ -1,12 +1,12 @@ [[painless-comments]] === Comments -Use the `//` token anywhere on a line to specify a single-line comment. All -characters from the `//` token to the end of the line are ignored. Use an -opening `/*` token and a closing `*/` token to specify a multi-line comment. -Multi-line comments can start anywhere on a line, and all characters in between -the `/*` token and `*/` token are ignored. Comments can be included anywhere -within a script. +Use a comment to annotate or explain code within a script. Use the `//` token +anywhere on a line to specify a single-line comment. All characters from the +`//` token to the end of the line are ignored. Use an opening `/*` token and a +closing `*/` token to specify a multi-line comment. Multi-line comments can +start anywhere on a line, and all characters in between the `/*` token and `*/` +token are ignored. Comments can be included anywhere within a script. *Grammar* [source,ANTLR4] diff --git a/docs/painless/painless-identifiers.asciidoc b/docs/painless/painless-identifiers.asciidoc index 17073e3d4c415..7762f56cb7b23 100644 --- a/docs/painless/painless-identifiers.asciidoc +++ b/docs/painless/painless-identifiers.asciidoc @@ -1,10 +1,10 @@ [[painless-identifiers]] === Identifiers -Specify identifiers to <>, <>, and -<> variables, <>, and -<>. <> and -<> cannot be used as identifiers. +Use an identifier as a named token to specify a +<>, <>, +<>, <>, or function. +<> cannot be used as identifiers. *Grammar* [source,ANTLR4] diff --git a/docs/painless/painless-keywords.asciidoc b/docs/painless/painless-keywords.asciidoc index cb3bafbd20f13..39a2201fd2b4b 100644 --- a/docs/painless/painless-keywords.asciidoc +++ b/docs/painless/painless-keywords.asciidoc @@ -1,9 +1,9 @@ [[painless-keywords]] === Keywords -The keywords in the table below are reserved for built-in language -features. These keywords cannot be used as -<> or <>. +Keywords are reserved tokens for built-in language features and cannot be used +as <> within a script. The following are +keywords: [cols="^1,^1,^1,^1,^1"] |==== diff --git a/docs/painless/painless-lang-spec.asciidoc b/docs/painless/painless-lang-spec.asciidoc index ba6595000ae2f..5e6b84d8c57d1 100644 --- a/docs/painless/painless-lang-spec.asciidoc +++ b/docs/painless/painless-lang-spec.asciidoc @@ -6,7 +6,7 @@ Painless syntax is similar to Java syntax along with some additional features such as dynamic typing, Map and List accessor shortcuts, and array initializers. As a direct comparison to Java, there are some important differences, especially related to the casting model. For more detailed -conceptual information about the basic constructs that Java and Painless share, +conceptual information about the basic constructs that Painless and Java share, refer to the corresponding topics in the https://docs.oracle.com/javase/specs/jls/se8/html/index.html[Java Language Specification]. diff --git a/docs/painless/painless-literals.asciidoc b/docs/painless/painless-literals.asciidoc index 2588b964cbf32..ebf7eaa07b657 100644 --- a/docs/painless/painless-literals.asciidoc +++ b/docs/painless/painless-literals.asciidoc @@ -1,18 +1,19 @@ [[painless-literals]] === Literals -Use literals to specify different types of values directly in a script. +Use a literal to specify a value directly in an +<>. [[integers]] ==== Integers -Use integer literals to specify an integer value in decimal, octal, or hex -notation of the <> `int`, `long`, `float`, +Use an integer literal to specify an integer type value in decimal, octal, or +hex notation of a <> `int`, `long`, `float`, or `double`. Use the following single letter designations to specify the -<>: `l` or `L` for `long`, `f` or `F` for -`float`, and `d` or `D` for `double`. If not specified, the type defaults to -`int`. Use `0` as a prefix to specify an integer literal as octal, and use -`0x` or `0X` as a prefix to specify an integer literal as hex. +primitive type: `l` or `L` for `long`, `f` or `F` for `float`, and `d` or `D` +for `double`. If not specified, the type defaults to `int`. Use `0` as a prefix +to specify an integer literal as octal, and use `0x` or `0X` as a prefix to +specify an integer literal as hex. *Grammar* [source,ANTLR4] @@ -46,11 +47,10 @@ HEX: '-'? '0' [xX] [0-9a-fA-F]+ [lL]?; [[floats]] ==== Floats -Use floating point literals to specify a floating point value of the -<> `float` or `double`. Use the following -single letter designations to specify the <>: -`f` or `F` for `float` and `d` or `D` for `double`. If not specified, the type -defaults to `double`. +Use a floating point literal to specify a floating point type value of a +<> `float` or `double`. Use the following +single letter designations to specify the primitive type: `f` or `F` for `float` +and `d` or `D` for `double`. If not specified, the type defaults to `double`. *Grammar* [source,ANTLR4] @@ -81,7 +81,7 @@ EXPONENT: ( [eE] [+\-]? [0-9]+ ); [[strings]] ==== Strings -Use string literals to specify <> values with +Use a string literal to specify a <> value with either single-quotes or double-quotes. Use a `\"` token to include a double-quote as part of a double-quoted string literal. Use a `\'` token to include a single-quote as part of a single-quoted string literal. Use a `\\` @@ -117,6 +117,6 @@ STRING: ( '"' ( '\\"' | '\\\\' | ~[\\"] )*? '"' ) [[characters]] ==== Characters -Character literals cannot be specified directly. Instead, use the -<> to convert -<> values into <> values. +A character literal cannot be specified directly. Instead, use the +<> to convert a `String` type value +into a `char` type value. diff --git a/docs/painless/painless-types.asciidoc b/docs/painless/painless-types.asciidoc index 2ec87c8806414..d9aea01c21a79 100644 --- a/docs/painless/painless-types.asciidoc +++ b/docs/painless/painless-types.asciidoc @@ -10,7 +10,7 @@ belongs to one of the following categories: <>, [[primitive-types]] ==== Primitive Types -A primitive type represents basic data build natively into the JVM and is +A primitive type represents basic data built natively into the JVM and is allocated to non-heap memory. Declare a primitive type <>, and assign it a primitive type value for evaluation during later operations. The default value for a newly-declared @@ -114,7 +114,7 @@ multiple pieces of data (member fields) and logic to manipulate that data A reference type instance is a single set of data for one reference type object allocated to the heap. Use the <> to allocate a reference type -instance. Use a reference type instance to read from, write to, and manipulate +instance. Use a reference type instance to load from, store to, and manipulate complex data. A reference type value refers to a reference type instance, and multiple @@ -139,8 +139,8 @@ static member field:: A static member field is a named and typed piece of data. Each reference type *object* contains one set of data representative of its static member fields. Use the <> in correspondence with the -reference type object name to access a static member field for reading and -writing to a specific reference type *object*. No reference type instance +reference type object name to access a static member field for loading and +storing to a specific reference type *object*. No reference type instance allocation is necessary to use a static member field. non-static member field:: @@ -148,7 +148,7 @@ non-static member field:: A non-static member field is a named and typed piece of data. Each reference type *instance* contains one set of data representative of its reference type object's non-static member fields. Use the -<> for reading and writing to a non-static +<> for loading and storing to a non-static member field of a specific reference type *instance*. An allocated reference type instance is required to use a non-static member field. @@ -162,8 +162,8 @@ allocation is necessary to use a static member method. non-static member method:: A non-static member method is a function called on a reference type *instance*. -A non-static member method called on a reference type instance can read from and -write to non-static member fields of that specific reference type instance. Use +A non-static member method called on a reference type instance can load from and +store to non-static member fields of that specific reference type instance. Use the <> in correspondence with a specific reference type instance to call a non-static member method. An allocated reference type instance is required to use a non-static member method. @@ -334,8 +334,8 @@ types and reference types directly when performance is critical. The `String` type is a specialized reference type that does not require explicit allocation. Use a <> to directly evaluate a -`String` type value. While not required, -the <> can allocate `String` type +`String` type value. While not required, the +<> can allocate `String` type instances. *Examples* @@ -401,8 +401,8 @@ argument refers to no array type instance. Use the <> to retrieve the length of an array type value as an int type value. Use the -<> to read and write to individual values -within an array type value. +<> to load from and store to individual +values within an array type value. When an array type instance is allocated with multiple dimensions using the range `[2, d]` where `d >= 2`, each dimension in the range `[1, d-1]` is also diff --git a/docs/painless/painless-variables.asciidoc b/docs/painless/painless-variables.asciidoc index 683acd2dcdf8d..8b8782b151132 100644 --- a/docs/painless/painless-variables.asciidoc +++ b/docs/painless/painless-variables.asciidoc @@ -1,31 +1,31 @@ [[painless-variables]] === Variables -<> variables to <> values for -<> in expressions. Specify variables as a -<>, <>, or -<>. Variable operations follow the structure of a -standard JVM in relation to instruction execution and memory usage. +A variable loads and stores a value for evaluation during +<>. [[declaration]] ==== Declaration -Declare variables before use with the format of <> -<>. Declare <> -variables using an opening `[` token and a closing `]` token for each -dimension directly after the <>. Specify a -comma-separated list of <> following the -<> to declare multiple variables in a single statement. -Use an <> statement combined with a declaration -statement to immediately assign a value to a variable. Variables not -immediately assigned a value will have a default value assigned implicitly -based on the <>. +Declare a variable before use with the format of <> +followed by <>. Declare an +<> variable using an opening `[` token and a closing `]` +token for each dimension directly after the identifier. Specify a +comma-separated list of identifiers following the type to declare multiple +variables in a single statement. Use an <> +combined with a declaration to immediately assign a value to a variable. +A variable not immediately assigned a value will have a default value assigned +implicitly based on the type. + +*Errors* + +* If a variable is used prior to or without declaration. *Grammar* [source,ANTLR4] ---- declaration : type ID assignment? (',' ID assignment?)*; -type: ID ('[' ']')*; +type: ID ('.' ID)* ('[' ']')*; assignment: '=' expression; ---- @@ -45,32 +45,35 @@ assignment: '=' expression; ---- + <1> declare `int x`; - assign default value of `null` to `x` + assign default `null` to `x` <2> declare `List y`; - assign default value of `null` to `y` + assign default `null` to `y` <3> declare `int x`; - assign default value of `int 0` to `x`; + assign default `int 0` to `x`; declare `int y`; - assign value of `int 5` to `y`; + assign `int 5` to `y`; declare `int z`; - assign default value of `int 0` to `z`; + assign default `int 0` to `z`; <4> declare `def d`; - assign default value of `null` to `d` + assign default `null` to `d` <5> declare `int i`; - assign value of `int 10` to `i` + assign `int 10` to `i` <6> declare `float[] f`; - assign default value of `null` to `f` + assign default `null` to `f` <7> declare `Map[][] m`; - assign default value of `null` to `m` + assign default `null` to `m` [[assignment]] ==== Assignment -Use the `equals operator '='` to assign a value to a variable. Any expression +Use the *assignment operator* to store a value in a variable. Any operation that produces a value can be assigned to any variable as long as the -<> are the same or the resultant -<> can be implicitly <> to -the variable <>. +<> are the same or the resultant type can be +<> to the variable type. + +*Errors* + +* If the type of value is unable to match the type of variable. *Grammar* [source,ANTLR4] @@ -80,7 +83,7 @@ assignment: ID '=' expression *Examples* -* Variable assignment with an <>. +* Variable assignment with an integer literal. + [source,Painless] ---- @@ -89,10 +92,10 @@ assignment: ID '=' expression ---- + <1> declare `int i`; - assign default value of `int 0` to `i` -<2> assign value of `int 10` to `i` + assign default `int 0` to `i` +<2> assign `int 10` to `i` + -* <> combined with immediate variable assignment. +* Declaration combined with immediate assignment. + [source,Painless] ---- @@ -101,12 +104,11 @@ assignment: ID '=' expression ---- + <1> declare `int i`; - assign value of `int 10` to `i` + assign `int 10` to `i` <2> declare `double j`; - assign value of `double 2.0` to `j` + assign `double 2.0` to `j` + -* Assignment of one variable to another using - <>. +* Assignment of one variable to another using primitive types. + [source,Painless] ---- @@ -115,13 +117,12 @@ assignment: ID '=' expression ---- + <1> declare `int i`; - assign value of `int 10` to `i` + assign `int 10` to `i` <2> declare `int j`; access `i` -> `int 10`; - assign value of `int 10` to `j` + assign `int 10` to `j` + -* Assignment with <> using the - <>. +* Assignment with reference types using the *new instance operator*. + [source,Painless] ---- @@ -131,15 +132,13 @@ assignment: ID '=' expression + <1> declare `ArrayList l`; allocate `ArrayList` instance -> `ArrayList reference`; - assign value of `ArrayList reference` to `l` + assign `ArrayList reference` to `l` <2> declare `Map m`; allocate `HashMap` instance -> `HashMap reference`; - implicit cast value of `HashMap reference` to value of `Map reference` - -> `Map reference`; - assign value of `Map reference` to `m` + implicit cast `HashMap reference` to `Map reference` -> `Map reference`; + assign `Map reference` to `m` + -* Assignment of one variable to another using - <>. +* Assignment of one variable to another using reference types. + [source,Painless] ---- @@ -151,21 +150,19 @@ assignment: ID '=' expression + <1> declare `List l`; allocate `ArrayList` instance -> `ArrayList reference`; - implicit cast value of `ArrayList reference` to value of `List reference` - -> `List reference`; - assign value of `List reference` to `l` + implicit cast `ArrayList reference` to `List reference` -> `List reference`; + assign `List reference` to `l` <2> declare `List k`; - access value of `l` -> `List reference`; - assign value of `List reference` to `k`; + access `l` -> `List reference`; + assign `List reference` to `k`; (note `l` and `k` refer to the same instance known as a shallow-copy) <3> declare `List m`; - assign default value of `null` to `m` -<4> access value of `k` -> `List reference`; - assign value of `List reference` to `m`; + assign default `null` to `m` +<4> access `k` -> `List reference`; + assign `List reference` to `m`; (note `l`, `k`, and `m` refer to the same instance) + -* Assignment with the <> using the - <>. +* Assignment with an array type variable using the *new array operator*. + [source,Painless] ---- @@ -179,24 +176,24 @@ assignment: ID '=' expression ---- + <1> declare `int[] ia1`; - assign default value of `null` to `ia1` + assign default `null` to `ia1` <2> allocate `1-d int array` instance with `length [2]` -> `1-d int array reference`; - assign value of `1-d int array reference` to `ia1` -<3> access value of `ia1` -> `1-d int array reference`; - assign value of `int 1` to `index [0]` of `1-d int array reference` + assign `1-d int array reference` to `ia1` +<3> access `ia1` -> `1-d int array reference`; + assign `int 1` to `index [0]` of `1-d int array reference` <4> declare `int[] ib1`; - access value of `ia1` -> `1-d int array reference`; - assign value of `1-d int array reference` to `ib1`; + access `ia1` -> `1-d int array reference`; + assign `1-d int array reference` to `ib1`; (note `ia1` and `ib1` refer to the same instance known as a shallow copy) <5> declare `int[][] ic2`; allocate `2-d int array` instance with `length [2, 5]` -> `2-d int array reference`; - assign value of `2-d int array reference` to `ic2` -<6> access value of `ic2` -> `2-d int array reference`; - assign value of `int 2` to `index [1, 3]` of `2-d int array reference` -<7> access value of `ia1` -> `1-d int array reference`; - access value of `ic2` -> `2-d int array reference`; - assign value of `1-d int array reference` to + assign `2-d int array reference` to `ic2` +<6> access `ic2` -> `2-d int array reference`; + assign `int 2` to `index [1, 3]` of `2-d int array reference` +<7> access `ia1` -> `1-d int array reference`; + access `ic2` -> `2-d int array reference`; + assign `1-d int array reference` to `index [0]` of `2-d int array reference`; (note `ia1`, `ib1`, and `index [0]` of `ia2` refer to the same instance) From ae1ae75cd69d16912ae54c4d96facb5458d30b51 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Tue, 22 May 2018 11:03:58 -0700 Subject: [PATCH 27/27] Extra blank lines at end of docs. --- docs/painless/painless-casting.asciidoc | 2 +- docs/painless/painless-types.asciidoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/painless/painless-casting.asciidoc b/docs/painless/painless-casting.asciidoc index 430b45eb0dd55..a3624f9083145 100644 --- a/docs/painless/painless-casting.asciidoc +++ b/docs/painless/painless-casting.asciidoc @@ -453,4 +453,4 @@ type value is derived from what the `def` type value represents at run-time. add `float 1.0` and `float 2.0` -> `float 3.0`; assign `float 3.0` to `f`; (note this example illustrates promotion done at run-time as promotion - done at compile-time would have resolved to a `def` type value) \ No newline at end of file + done at compile-time would have resolved to a `def` type value) diff --git a/docs/painless/painless-types.asciidoc b/docs/painless/painless-types.asciidoc index d9aea01c21a79..a897b8e8a04f0 100644 --- a/docs/painless/painless-types.asciidoc +++ b/docs/painless/painless-types.asciidoc @@ -463,4 +463,4 @@ the array type `int[][]`. <3> declare `int i`; access `ia3` -> `3-d int array reference`; access `index [1, 2, 3]` of `3-d int array reference` -> `int 99`; - assign `int 99` to `i` \ No newline at end of file + assign `int 99` to `i`