Kotlin 1.4: non-spread named arguments for varargs

Author: ice-phoenix

docs/src/md/kotlin.core/declarations.md

@@ -451,6 +451,11 @@ If one wants to mix named and positional arguments, the argument list must confo
 
 > Note: in Kotlin version 1.3 and earlier, $PoN_i$ were restricted to positional arguments only.
 
+If one needs to provide a named argument to a [variable length parameter][Variable length parameters], it can be achieved via either regular named argument `arg = arr` or a spread operator expression form `arg = *arr`.
+In both cases type of `arr` must be a subtype of [$\ATS(\Array(\outV T))$][Array types] for a variable length parameter of type $T$.
+
+> Note: in Kotlin version 1.3 and earlier, only the spread operator expression form for named variable length arguments was supported.
+
 Kotlin also supports *default* parameters --- parameters which have a default value used in function invocation, if the corresponding argument is missing. Note that default parameters cannot be used to provide a value for positional argument *in the middle* of the positional argument list; allowing this would create an ambiguity of which argument for position $i$ is the correct one: explicit one provided by the developer or implicit one from the default value.
 
 ```kotlin
@@ -483,7 +488,7 @@ One of the parameters may be designated as being variable length (aka *vararg*).
 A parameter list $(p_1, \ldots, \text{vararg }p_i: P_i = v_i, \ldots, p_n)$ means a function may be called with any number of arguments in the i-th position.
 These arguments are represented inside function body $b$ as a value $p_i$ of type, which is the result of [*array type specialization*][Array types] of type $\Array(\outV P_i)$.
 
-> Important: we also consider variable length parameters to have such types for the purposes of type inference.
+> Important: we also consider variable length parameters to have such types for the purposes of type inference and named parameters.
 > TODO(Something else?)
 
 If a variable length parameter is not last in the parameter list, all subsequent arguments in the function invocation should be specified as named arguments.

docs/src/md/kotlin.core/expressions.md

@@ -977,11 +977,11 @@ As described in [the function declaration section][Function declaration], functi
 
 - Explicit receiver argument, used in calls with explicit receivers;
 - Normal arguments, provided directly inside the parentheses part of the call;
-- Named arguments in the form `identifier = value`, where `identifier` is a parameter name used at declaration-site of the function;
+- [Named arguments][Named, positional and default parameters] in the form `identifier = value`, where `identifier` is a parameter name used at declaration-site of the function;
 - [Variable length arguments][Variable length parameters], provided the same way as normal arguments;
 - A trailing lambda literal argument, specified outside the parentheses (see [lambda literal section][Lambda literals] for details).
 
-In addition to these, a function declaration may specify a number of default parameters, which allow one to omit specifying them at call-site, in which case their default value is used during the evaluation.
+In addition to these, a function declaration may specify a number of [default parameters][Named, positional and default parameters], which allow one to omit specifying them at call-site, in which case their default value is used during the evaluation.
 
 The evaluation of a function call begins with the evaluation of its explicit receiver, if it is present.
 Function arguments are then evaluated **in the order of their appearance in the function call** left-to-right, with no consideration on how the parameters of the function were specified during function declaration.
@@ -1041,7 +1041,7 @@ It is allowed to mix spread arguments with regular arguments, all fitting into t
 Spread operator expressions are not allowed in any other context.
 See [Variable length parameter][Variable length parameters] section for details.
 
-The type of a spread argument must be a subtype of [$\ATS(T)$][Array types] for a variable length parameter of type $T$.
+The type of a spread argument must be a subtype of [$\ATS(\Array(\outV T))$][Array types] for a variable length parameter of type $T$.
 
 > Example: for parameter `vararg a: Int` the type of a corresponding spread argument must be a subtype of `IntArray`, for parameter `vararg b: T` where `T` is a classifier type the type of a corresponding spread argument must be a subtype of `Array<out T>`.
 

docs/src/md/kotlin.core/type-system.md

@@ -205,7 +205,7 @@ However, they are **not** related by subtyping; meaning one cannot pass a `Boole
 
 > Note: specialized and non-specialized array types match modulo their iterator types, which are also specialized; `Iterator<Int>` is specialized to `IntIterator`.
 
-*Array type specialization* $\ATS(T)$ is a transformation of a generic $\Array(T)$ type to a corresponding specialized version, which works as follows.
+*Array type specialization* $\ATS(A)$ is a transformation of a generic $\Array(T)$ type to a corresponding specialized version, which works as follows.
 
 * if $\Array(T)$ has a specialized version `TArray`, $\ATS(\Array(T)) = \texttt{TArray}$
 * if $\Array(T)$ does not have a specialized version, $\ATS(\Array(T)) = \Array(T)$