MethodHandles.CollectArguments(MethodHandle, Int32, MethodHandle) Method

Definition

Namespace:

Java.Lang.Invoke

Assembly:

Mono.Android.dll

Adapts a target method handle by pre-processing a sub-sequence of its arguments with a filter (another method handle).

[Android.Runtime.Register("collectArguments", "(Ljava/lang/invoke/MethodHandle;ILjava/lang/invoke/MethodHandle;)Ljava/lang/invoke/MethodHandle;", "", ApiSince=26)]
public static Java.Lang.Invoke.MethodHandle? CollectArguments (Java.Lang.Invoke.MethodHandle? target, int pos, Java.Lang.Invoke.MethodHandle? filter);

[<Android.Runtime.Register("collectArguments", "(Ljava/lang/invoke/MethodHandle;ILjava/lang/invoke/MethodHandle;)Ljava/lang/invoke/MethodHandle;", "", ApiSince=26)>]
static member CollectArguments : Java.Lang.Invoke.MethodHandle * int * Java.Lang.Invoke.MethodHandle -> Java.Lang.Invoke.MethodHandle

Parameters

target

MethodHandle

the method handle to invoke after filtering the subsequence of arguments

pos

Int32

the position of the first adapter argument to pass to the filter, and/or the target argument which receives the result of the filter

filter

MethodHandle

method handle to call on the subsequence of arguments

Returns

MethodHandle

method handle which incorporates the specified argument subsequence filtering logic

Attributes

RegisterAttribute

Remarks

Adapts a target method handle by pre-processing a sub-sequence of its arguments with a filter (another method handle). The pre-processed arguments are replaced by the result (if any) of the filter function. The target is then called on the modified (usually shortened) argument list.

If the filter returns a value, the target must accept that value as its argument in position pos, preceded and/or followed by any arguments not passed to the filter. If the filter returns void, the target must accept all arguments not passed to the filter. No arguments are reordered, and a result returned from the filter replaces (in order) the whole subsequence of arguments originally passed to the adapter.

The argument types (if any) of the filter replace zero or one argument types of the target, at position pos, in the resulting adapted method handle. The return type of the filter (if any) must be identical to the argument type of the target at position pos, and that target argument is supplied by the return value of the filter.

In all cases, pos must be greater than or equal to zero, and pos must also be less than or equal to the target's arity.

<b>Example:</b> <blockquote>

{@code
            import static java.lang.invoke.MethodHandles.*;
            import static java.lang.invoke.MethodType.*;
            ...
            MethodHandle deepToString = publicLookup()
              .findStatic(Arrays.class, "deepToString", methodType(String.class, Object[].class));

            MethodHandle ts1 = deepToString.asCollector(String[].class, 1);
            assertEquals("[strange]", (String) ts1.invokeExact("strange"));

            MethodHandle ts2 = deepToString.asCollector(String[].class, 2);
            assertEquals("[up, down]", (String) ts2.invokeExact("up", "down"));

            MethodHandle ts3 = deepToString.asCollector(String[].class, 3);
            MethodHandle ts3_ts2 = collectArguments(ts3, 1, ts2);
            assertEquals("[top, [up, down], strange]",
                         (String) ts3_ts2.invokeExact("top", "up", "down", "strange"));

            MethodHandle ts3_ts2_ts1 = collectArguments(ts3_ts2, 3, ts1);
            assertEquals("[top, [up, down], [strange]]",
                         (String) ts3_ts2_ts1.invokeExact("top", "up", "down", "strange"));

            MethodHandle ts3_ts2_ts3 = collectArguments(ts3_ts2, 1, ts3);
            assertEquals("[top, [[up, down, strange], charm], bottom]",
                         (String) ts3_ts2_ts3.invokeExact("top", "up", "down", "strange", "charm", "bottom"));
            }

</blockquote>

Here is pseudocode for the resulting adapter: <blockquote>

{@code
            T target(A...,V,C...);
            V filter(B...);
            T adapter(A... a,B... b,C... c) {
              V v = filter(b...);
              return target(a...,v,c...);
            }
            // and if the filter has no arguments:
            T target2(A...,V,C...);
            V filter2();
            T adapter2(A... a,C... c) {
              V v = filter2();
              return target2(a...,v,c...);
            }
            // and if the filter has a void return:
            T target3(A...,C...);
            void filter3(B...);
            void adapter3(A... a,B... b,C... c) {
              filter3(b...);
              return target3(a...,c...);
            }
            }

</blockquote>

A collection adapter collectArguments(mh, 0, coll) is equivalent to one which first "folds" the affected arguments, and then drops them, in separate steps as follows: <blockquote>

{@code
            mh = MethodHandles.dropArguments(mh, 1, coll.type().parameterList()); //step 2
            mh = MethodHandles.foldArguments(mh, coll); //step 1
            }

</blockquote> If the target method handle consumes no arguments besides than the result (if any) of the filter coll, then collectArguments(mh, 0, coll) is equivalent to filterReturnValue(coll, mh). If the filter method handle coll consumes one argument and produces a non-void result, then collectArguments(mh, N, coll) is equivalent to filterArguments(mh, N, coll). Other equivalences are possible but would require argument permutation.

Java documentation for java.lang.invoke.MethodHandles.collectArguments(java.lang.invoke.MethodHandle, int, java.lang.invoke.MethodHandle).

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.