Args

Args , also known as Generic Arguments, is a class designed to represent arguments of specified types. It behaves as an immutable aggregate type like Record , albeit with a maximum of three arguments.

Tip

If your project supports Record , it is recommended to use it instead of the generic arguments.

It is usefult to use in the following cases:

• Function Argument Bundling: When you need to pass multiple arguments to a function via a single argument.
• Argument Extraction: When you required to get the arguments of a function as a list.
• Adaptation for Single-Argument Expectation: In situations where a class or function anticipates a function with a single argument, but you need to provide it with a function that accepts multiple arguments, the ary method is very useful. This adaptation is particularly valuable in contexts like employing the Memo class or the UseAsyncState.withArg hook, where compatibility hinges on transforming a multi-argument function into a single-argument one.

Classes

Reactter provides these generic arguments classes:

• Args<A> : represents one or more arguments of A type.
• Args1<A> : represents a argument of A type.
• Args2<A, A2> : represents two arguments of A , A2 type consecutively.
• Args3<A, A2, A3> : represents three arguments of A , A2 , A3 type consecutively.
• ArgsX2<A> : represents two arguments of A type.
• ArgsX3<A> : represents three arguments of A type.

Properties & Methods

In each of the methods it provides these properties and methods:

• arguments: A property to get the list of arguments.
• arg1: A property to get the first argument.
• arg2( Args2 , Args3 , ArgsX2 , ArgsX3 only): A property to get the second argument.
• arg3( Args3 , ArgsX3 only): A property to get the third argument.
• toList : A method to get the list of arguments T type.

Usage

Define Arguments

To use it, you can create an instance and provide the specified types of arguments, e.g.:

void myFunction(Args2<int, String> args) {
  print(args.arguments); // [1, "test"]
}

myFunction(Args2(1, "test"));

Alternatively, you can access the arg1, arg2, arg3 properties to retrieve individual arguments, like so:

void myFunction(Args3<int, String, bool> args) {
  print(args.arg1); // 1
  print(args.arg2); // "test"
  print(args.arg3); // true
}

myFunction(Args3(1, "test", true));

The ArgsX2 and ArgsX3 classes are similar to the Args2 and Args3 classes, but these classes are set to the same type of arguments.

void myFunction(ArgsX3<int> args) {
  // get the list of arguments
  print(args.arguments); // [1, 2, 3]
  // or get the individual arguments
  print(args.arg1); // 1
  print(args.arg2); // 2
  print(args.arg3); // 3
}

myFunction(ArgsX3(1, 2, 3));

Type compatibility

The Args classes are compatible with each other, so you can pass an Args instance to a function that expects an Args instance with fewer arguments, e.g.:

void myFunction(Args2<int, String> args) {
  print(args.arg1); // 1
  print(args.arg2); // "hello"
}

myFunction(Args3(1, "hello", false));

The ArgsX2 and ArgsX3 classes are compatible with the Args2 and Args3 classes, respectively, so you can pass an ArgsX2 instance to a function that expects an Args2 instance with the same type arguments, e.g.:

void myFunction(ArgsX2<int> args) {
  print(args.arg1); // 1
  print(args.arg2); // 2
}

// these are valid
myFunction(Args2(1, 2));
myFunction(Args3(1, 2, 3));
myFunction(ArgsX3(1, 2, 3));

// these are invalid
myFunction(Args([1, 2]));
myFunction(Args1(1));
myFunction(Args2(1, "foo"));
myFunction(Args3(1, "bar", false));

Equality Comparation

The Args classes are comparable, so you can compare them with each other. Two Args instances are considered equal if they contain the same number of arguments and the values in each corresponding position match, e.g.:

// these are equal
print(Args1(1) == Args1(1)); // true
print(Args2(2, "foo") == Args2(2, "foo")); // true
print(ArgsX3(3, "bar", false) == ArgsX3(3, "bar", false)); // true
print(Args([1, "foo"]) == Args2(1, "foo")); // true
print(Args2(2, "bar") == ArgsX2(2, "bar")); // true
print(ArgsX3(3, "foo", false) == Args([3, "foo", false])); // true

// The argument does not match
print(Args1(1) == Args1(2)); // false
// The argument does not match because Map object has a different reference
print(Args1({"foo": "bar"}) == Args1({"foo": "bar"})); // false
// Different number of arguments
print(Args([1, 2]) == Args1([1, 2])); // false
print(Args2(2, "foo") == Args3(2, "foo", false)); // false
print(Args3(1, "foo", false) == Args([1, "foo", false, "bar"])); // false
// Different type of arguments
print(ArgsX3(3, "bar", false) == Args3("bar", 3, false)); // false

Ary Function

The arity or adicity of a function is the number of arguments (i.e. inputs or parameters) it takes.

Use ary of Function extention to convert any Function with positional arguments to Function with generic argument, e.g.:

import 'package:reactter/reactter.dart';

// The `ary` extension is available for all functions with positional arguments
int addNum(int num1, int num2) => num1 + num2;
final addNumAry = myFunction.ary; // int Function(Args2(int, int))
addNumAry(Arg2(1, 1)); // 2

// Alternatively, it can be called directly
addNum.ary(ArgX2(2, 2)); // 4

// Any function with any number of arguments can be converted
void foo(int arg1, String arg2, bool arg3, List<int> arg4) => print("$arg1, $arg2, $arg3, $arg4");
final fooAry = foo.ary; // void Function(Args<dynamic> args)
fooAry(Args([1, "test", true, [1, 2, 3]])); // 1, test, true, [1, 2, 3]

IMPORTANT!!

The ary does not support functions with named arguments. If it is used with a Function with named arguments, it will throw an ERROR in runtime. So, make sure to use it with a function with positional arguments only.