params: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
m (Text replacement - "<code>([^ ]*)\[\[([a-zA-Z][a-zA-Z0-9_]+)\]\]([^ ]*) ([^ ]*) ([^ ]*) ([^ ]*)<\/code>" to "<code>$1$2$3 $4 $5 $6</code>")
No edit summary
 
(30 intermediate revisions by 3 users not shown)
Line 10: Line 10:
|descr= Parses input argument into array of [[private]] variables. When used without argument, as shown in main syntax, internal variable [[Magic Variables#this|_this]], which is usually available inside functions and event handlers, is used as argument.<br><br>
|descr= Parses input argument into array of [[private]] variables. When used without argument, as shown in main syntax, internal variable [[Magic Variables#this|_this]], which is usually available inside functions and event handlers, is used as argument.<br><br>
In addition to simple parsing directly into variables, input can be tested in case it is undefined, of the wrong type or of the wrong size (if array) and substituted if necessary with default values. Since Arma 3 v1.54, onscreen errors are displayed for when the input is of the wrong type or size.
In addition to simple parsing directly into variables, input can be tested in case it is undefined, of the wrong type or of the wrong size (if array) and substituted if necessary with default values. Since Arma 3 v1.54, onscreen errors are displayed for when the input is of the wrong type or size.
{{Feature|Warning| All variables names must start with underscore and be enclosed in quotes: {{hl|c= [[params]] [<span style{{=}}"color:red;font-weight:bold">"_</span>myVar1<span style{{=}}"color:red;font-weight:bold">"</span>, <span style{{=}}"color:red;font-weight:bold">"_</span>myVar2<span style{{=}}"color:red;font-weight:bold">"</span>];}}
{{Feature|warning| All variables names must start with underscore and be enclosed in quotes: {{hl|c= [[params]] [<span style{{=}}"color:red;font-weight:bold">"_</span>myVar1<span style{{=}}"color:red;font-weight:bold">"</span>, <span style{{=}}"color:red;font-weight:bold">"_</span>myVar2<span style{{=}}"color:red;font-weight:bold">"</span>];}}
}}
}}
{{Feature|Informative| It is a good practice to make your local variables '''private''' (through [[private]] or [[params]]) in order to avoid overwriting a local variable of the same name.}}
{{Feature|informative| It is a good practice to make your local variables '''private''' (through [[private]] or [[params]]) in order to avoid overwriting a local variable of the same name.}}


|s1= [[params]] [element1, element2,...elementN]
|s1= [[params]] [element1, element2, ...]


|p1= elementN: [[String]] or [[Array]]
|p1= elementN: [[String]] or [[Array]]
* [[String]]:name of the [[private]] variable (must begin with underscore _, e.g. "_myVar")
* [[String]]:name of the [[private]] variable (must begin with underscore _, e.g. "_myVar", or can be an empty string "", in which case the element is skipped)
* [[Array]] format [variableName, defaultValue, expectedDataTypes, expectedArrayCount]:
* [[Array]] format [variableName, defaultValue, expectedDataTypes, expectedArrayCount]:
** variableName: [[String]] - name of a [[private]] variable (must begin with underscore _, e.g. "_myVar")
** variableName: [[String]] - name of a [[private]] variable (must begin with underscore _, e.g. "_myVar")
Line 26: Line 26:
|r1= [[Boolean]] - [[false]] if error occurred or default value has been used, otherwise [[true]]
|r1= [[Boolean]] - [[false]] if error occurred or default value has been used, otherwise [[true]]


|s2= argument [[params]] [element1, element2,...elementN]
|s2= argument [[params]] [element1, element2, ...]


|p21= argument: [[Anything]] - A usual array of params is expected. If a non-array argument is passed, it will be converted to 1 element array
|p21= argument: [[Anything]] - a usual array of params is expected. If a non-array argument is passed, it will be converted to 1 element array


|p22= elementN: [[String]] or [[Array]]
|p22= elementN: [[String]] or [[Array]]
* [[String]]:name of the [[private]] variable (must begin with underscore _, e.g. "_myVar")
* [[String]]:name of the [[private]] variable (must begin with underscore _, e.g. "_myVar", or can be an empty string "", in which case the element is skipped)
* [[Array]] format [variableName, defaultValue, expectedDataTypes, expectedArrayCount]:
* [[Array]] format [variableName, defaultValue, expectedDataTypes, expectedArrayCount]:
** variableName: [[String]] - name of a [[private]] variable (must begin with underscore _, e.g. "_myVar")
** variableName: [[String]] - name of a [[private]] variable (must begin with underscore _, e.g. "_myVar")
Line 40: Line 40:
|r2= [[Boolean]] - [[false]] if error occurred or default value has been used, otherwise [[true]]
|r2= [[Boolean]] - [[false]] if error occurred or default value has been used, otherwise [[true]]


|x1= <code>[1, 2, 3] [[call]] {
|x1= <sqf>
[[private]] ["_one", "_two", "_three"];
[1, 2, 3] call {
_one = _this [[select]] 0;
private ["_one", "_two", "_three"];
_two = _this [[select]] 1;
_one = _this select 0;
_three = _this [[select]] 2;
_two = _this select 1;
_three = _this select 2;
// ...
// ...
};
};


// Same as above, only using params
// Same as above, only using params
[1, 2, 3] [[call]] {
[1, 2, 3] call {
[[params]] ["_one", "_two", "_three"];
params ["_one", "_two", "_three"];
// ...
// ...
};</code>
};
</sqf>


|x2= <code>[123] [[call]] {
|x2= <sqf>
[[params]] ["_myvar"];
[123] call {
params ["_myvar"];
};
};


// Below would produce the same result as above
// Below would produce the same result as above
123 [[call]] {
123 call {
[[params]] ["_myvar"];
params ["_myvar"];
};</code>
};
</sqf>


|x3= <code>position [[player]] [[params]] ["", "", "_z"];
|x3= Skipping some array elements:
[[if]] (_z > 10) [[then]] {
<sqf>
[[hint]] "YOU ARE FLYING!";
position player params ["", "", "_z"];
};</code>
if (_z > 10) then {
hint "YOU ARE FLYING!";
};
</sqf>


|x4= <code>[1, [[nil]], 2] [[params]] ["_var1", "_var2", "_var3"];
|x4= <sqf>
[1, nil, 2] params ["_var1", "_var2", "_var3"];
// All 3 variables are made private but only _var1 and _var3 are defined
// All 3 variables are made private but only _var1 and _var3 are defined


[1, [[nil]], 2] [[params]] ["_var1", ["_var2", 23], "_var3"];
[1, nil, 2] params ["_var1", ["_var2", 23], "_var3"];
// All 3 variables are private and defined</code>
// All 3 variables are private and defined
</sqf>


|x5= <code>[1, 2] [[call]] {
|x5= <sqf>
[[if]] (![[params]] ["_var1", "_var2", ["_var3", [[true]], [<nowiki/>[[true]]]]]) [[exitWith]] {
[1, 2] call {
[[hint]] [[str]] [_var1, _var2, _var3];
if (!params ["_var1", "_var2", ["_var3", true, [true]]]) exitWith {
hint str [_var1, _var2, _var3];
};
};
};
};
Line 82: Line 92:
// Script exits, default value was used due to missing value
// Script exits, default value was used due to missing value


[1, 2, 3] [[call]] {
[1, 2, 3] call {
[[if]] (![[params]] ["_var1", "_var2", ["_var3", [[true]], [<nowiki/>[[true]]]]]) [[exitWith]] {
if (!params ["_var1", "_var2", ["_var3", true, [true]]]) exitWith {
[[hint]] [[str]] [_var1, _var2, _var3];
hint str [_var1, _var2, _var3];
};
};
};
};
// The hint shows [1,2,true]
// The hint shows [1,2,true]
// Script exits, default value was used due incorrect value type</code>
// Script exits, default value was used due incorrect value type
</sqf>


|x6= <code>[1, "ok", [1, 2, 3]] [[call]] {
|x6= <sqf>
[[if]] (![[params]] [
[1, "ok", [1, 2, 3]] call {
if (!params [
["_var1", 0, [0]],
["_var1", 0, [0]],
["_var2", "", [""]],
["_var2", "", [""]],
["_var3", [0,0,0], [<nowiki/>[], [[objNull]], 0], [2,3]]
["_var3", [0,0,0], [[], objNull, 0], [2,3]]
]) [[exitWith]] {};
]) exitWith {};
[[hint]] "ok";
hint "ok";
};
};
// Passes validation
// Passes validation


[1, 2, [3, 4, 5]] [[call]] {
[1, 2, [3, 4, 5]] call {
[[if]] (![[params]] ["_var1", "_var2", ["_var3", [], [<nowiki/>[], [[objNull]], 0], 0]]) [[exitWith]] {};
if (!params ["_var1", "_var2", ["_var3", [], [[], objNull, 0], 0]]) exitWith {};
[[hint]] "ok";
hint "ok";
};
};
// Fails, because passed array is expected to be of 0 length, i.e. empty</code>
// Fails, because passed array is expected to be of 0 length, i.e. empty
|x7= <code>position player params ["_x", "_y"];
</sqf>
player setPos [_x, _y, 100];</code>


|x8= <code>[1, 2, 3, [4, 5, 6]] call {
|x8= <sqf>
[[params]] ["_one", "_two", "_three"];
[1, 2, 3, [4, 5, 6]] call {
_this [[select]] 3 [[params]] ["_four", "_five", "_six"];
params ["_one", "_two", "_three"];
};</code>
_this select 3 params ["_four", "_five", "_six"];
};
</sqf>


|x9= <code>{
|x9= <sqf>
_x [[params]] ["_group", "_index"];
{
_x params ["_group", "_index"];
// ...
// ...
} [[forEach]] [[waypoints]] [[group]] [[player]];
} forEach waypoints group player;


fn_someFnc = {
fn_someFnc = {
[[params]] ["_position", ["_direction", 0], ["_name", ""]];
params ["_position", ["_direction", 0], ["_name", ""]];
// Extract the x, y, and z from "_position" array:
// Extract the x, y, and z from "_position" array:
_position [[params]] ["_x", "_y", "_z"];
_position params ["_x", "_y", "_z"];
// ...
// ...
};
};


<nowiki>[</nowiki>position player, direction player, name player] call fn_someFnc;</code>
[position player, direction player, name player] call fn_someFnc;
</sqf>


|x10= <code>player addEventHandler ["HitPart", {
|x10= <sqf>
_this [[select]] 0 [[params]] ["_target", "_shooter", "_projectile"];
player addEventHandler ["HitPart", {
}];</code>
_this select 0 params ["_target", "_shooter", "_projectile"];
}];
</sqf>


|seealso= [[param]] [[select]] [[#]] [[_this]] [[isEqualTypeAll]] [[isEqualType]] [[isEqualTypeParams]] [[isEqualTypeArray]] [[isEqualTypeAny]]
|seealso= [[param]] [[select]] [[#]] [[_this]] [[isEqualTypeAll]] [[isEqualType]] [[isEqualTypeParams]] [[isEqualTypeArray]] [[isEqualTypeAny]]
Line 137: Line 154:


<dt></dt>
<dt></dt>
<dd class="notedate">Posted on November 3, 2016 - 04:07 (UTC)</dd>
<dd class="notedate">Posted on 2016-11-03 - 04:07 (UTC)</dd>
<dt class="note">[[User:Dedmen|Dedmen]]</dt>
<dt class="note">[[User:Dedmen|Dedmen]]</dt>
<dd class="note">
<dd class="note">
Line 143: Line 160:


Example:
Example:
<code>1 call {
<sqf>
params [ ["_number",0, [0]] ];
1 call {
params [["_number",0, [0]]];
};
};
or
or
[1] call {
[1] call {
params [ ["_number",0, [0]] ];
params [["_number",0, [0]]];
};</code>
};
</sqf>


But when the one Parameter is an array that parameter has to be inside of an array when the function is called<br>
But when the one Parameter is an array that parameter has to be inside of an array when the function is called<br>
Example:
Example:
<code>[1,2] call {
<sqf>
params [ ["_array", [], [[]], 2] ];
[1,2] call {
params [["_array", [], [[]], 2]];
}; // Fails
}; // Fails


<nowiki>[[1,2]]</nowiki> call {
[[1,2]] call {
params [ ["_array", [], [[]], 2] ];
params [["_array", [], [[]], 2]];
}; // Succeeds</code>
}; // Succeeds
</sqf>


</dd>
</dd>


<dt><dt>
<dt><dt>
<dd class="notedate">Posted on July 4, 2019 - 16:54 (UTC)</dd>
<dd class="notedate">Posted on 2019-07-04 - 16:54 (UTC)</dd>
<dt class="note">[[User:7erra|7erra]]</dt>
<dt class="note">[[User:7erra|7erra]]</dt>
<dd class="note">
<dd class="note">
It is valid to redefine the [[Magic Variables#this|_this]] variable and use [[params]] again like this:<br>
It is valid to redefine the [[Magic Variables#this|_this]] variable and use [[params]] again like this:<br>
<code>[1, 2, [3, 4]] call {
<sqf>
    params ["_one", "_two", "_this"];
[1, 2, [3, 4]] call {
    params ["_three", "_four"];
params ["_one", "_two", "_this"];
};</code>
params ["_three", "_four"];
};
</sqf>
</dd>
</dd>


Line 180: Line 203:
|timestamp= 20211101160030
|timestamp= 20211101160030
|text= Here's how to validate [[HashMap]] parameters:
|text= Here's how to validate [[HashMap]] parameters:
<code>_myHashMap = [[createHashMapFromArray]] [["a",1],["b",2],["c",3]];
<sqf>
_myHashMap = createHashMapFromArray [["a",1],["b",2],["c",3]];


[_myHashMap] call {
[_myHashMap] call {
[[params]] [["_theHashMap",[[createHashMap]],[<nowiki/>[[createHashMap]]]]];
params [["_theHashMap",createHashMap,[createHashMap]]];
};</code>
};
</sqf>
}}
}}

Latest revision as of 16:42, 21 October 2024

Hover & click on the images for description

Description

Description:
Parses input argument into array of private variables. When used without argument, as shown in main syntax, internal variable _this, which is usually available inside functions and event handlers, is used as argument.

In addition to simple parsing directly into variables, input can be tested in case it is undefined, of the wrong type or of the wrong size (if array) and substituted if necessary with default values. Since Arma 3 v1.54, onscreen errors are displayed for when the input is of the wrong type or size.
All variables names must start with underscore and be enclosed in quotes: params ["_myVar1", "_myVar2"];
It is a good practice to make your local variables private (through private or params) in order to avoid overwriting a local variable of the same name.
Groups:
VariablesArrays

Syntax

Syntax:
params [element1, element2, ...]
Parameters:
elementN: String or Array
  • String:name of the private variable (must begin with underscore _, e.g. "_myVar", or can be an empty string "", in which case the element is skipped)
  • Array format [variableName, defaultValue, expectedDataTypes, expectedArrayCount]:
    • variableName: String - name of a private variable (must begin with underscore _, e.g. "_myVar")
    • defaultValue: Anything - default value to return if input element is undefined, of the wrong type or of the wrong size (if array).
    • expectedDataTypes: Array of direct Data Types - (Optional) checks if passed value is one of listed Data Types. If not, default value is used instead. Empty array [] means every data type is accepted.
    • expectedArrayCount: Number or Array - (Optional) a single size or array of sizes. If passed input value is an array, checks that it has a certain number of elements. If not, default value is used instead. Empty array [] means any size is accepted.
Return Value:
Boolean - false if error occurred or default value has been used, otherwise true

Alternative Syntax

Syntax:
argument params [element1, element2, ...]
Parameters:
argument: Anything - a usual array of params is expected. If a non-array argument is passed, it will be converted to 1 element array
elementN: String or Array
  • String:name of the private variable (must begin with underscore _, e.g. "_myVar", or can be an empty string "", in which case the element is skipped)
  • Array format [variableName, defaultValue, expectedDataTypes, expectedArrayCount]:
    • variableName: String - name of a private variable (must begin with underscore _, e.g. "_myVar")
    • defaultValue: Anything - default value to return if input element is undefined, of the wrong type or of the wrong size (if array).
    • expectedDataTypes: Array of direct Data Types - (Optional) checks if passed value is one of listed Data Types. If not, default value is used instead. Empty array [] means every data type is accepted.
    • expectedArrayCount: Number or Array - (Optional) a single size or array of sizes. If passed input value is an array, checks that it has a certain number of elements. If not, default value is used instead. Empty array [] means any size is accepted.
Return Value:
Boolean - false if error occurred or default value has been used, otherwise true

Examples

Example 1:
[1, 2, 3] call { private ["_one", "_two", "_three"]; _one = _this select 0; _two = _this select 1; _three = _this select 2; // ... }; // Same as above, only using params [1, 2, 3] call { params ["_one", "_two", "_three"]; // ... };
Example 2:
[123] call { params ["_myvar"]; }; // Below would produce the same result as above 123 call { params ["_myvar"]; };
Example 3:
Skipping some array elements:
position player params ["", "", "_z"]; if (_z > 10) then { hint "YOU ARE FLYING!"; };
Example 4:
[1, nil, 2] params ["_var1", "_var2", "_var3"]; // All 3 variables are made private but only _var1 and _var3 are defined [1, nil, 2] params ["_var1", ["_var2", 23], "_var3"]; // All 3 variables are private and defined
Example 5:
[1, 2] call { if (!params ["_var1", "_var2", ["_var3", true, [true]]]) exitWith { hint str [_var1, _var2, _var3]; }; }; // The hint shows [1,2,true] // Script exits, default value was used due to missing value [1, 2, 3] call { if (!params ["_var1", "_var2", ["_var3", true, [true]]]) exitWith { hint str [_var1, _var2, _var3]; }; }; // The hint shows [1,2,true] // Script exits, default value was used due incorrect value type
Example 6:
[1, "ok", [1, 2, 3]] call { if (!params [ ["_var1", 0, [0]], ["_var2", "", [""]], ["_var3", [0,0,0], [[], objNull, 0], [2,3]] ]) exitWith {}; hint "ok"; }; // Passes validation [1, 2, [3, 4, 5]] call { if (!params ["_var1", "_var2", ["_var3", [], [[], objNull, 0], 0]]) exitWith {}; hint "ok"; }; // Fails, because passed array is expected to be of 0 length, i.e. empty
Example 8:
[1, 2, 3, [4, 5, 6]] call { params ["_one", "_two", "_three"]; _this select 3 params ["_four", "_five", "_six"]; };
Example 9:
{ _x params ["_group", "_index"]; // ... } forEach waypoints group player; fn_someFnc = { params ["_position", ["_direction", 0], ["_name", ""]]; // Extract the x, y, and z from "_position" array: _position params ["_x", "_y", "_z"]; // ... }; [position player, direction player, name player] call fn_someFnc;
Example 10:
player addEventHandler ["HitPart", { _this select 0 params ["_target", "_shooter", "_projectile"]; }];

Additional Information

See also:
param select # _this isEqualTypeAll isEqualType isEqualTypeParams isEqualTypeArray isEqualTypeAny

Notes

Report bugs on the Feedback Tracker and/or discuss them on the Arma Discord or on the Forums.
Only post proven facts here! Add Note
Posted on 2016-11-03 - 04:07 (UTC)
Dedmen
With a function only taking one Parameter, it doesn't matter whether the parameter is in an array or not:
Example:
1 call { params [["_number",0, [0]]]; }; or [1] call { params [["_number",0, [0]]]; };
But when the one Parameter is an array that parameter has to be inside of an array when the function is called
Example:
[1,2] call { params [["_array", [], [[]], 2]]; }; // Fails [[1,2]] call { params [["_array", [], [[]], 2]]; }; // Succeeds
Posted on 2019-07-04 - 16:54 (UTC)
7erra
It is valid to redefine the _this variable and use params again like this:
[1, 2, [3, 4]] call { params ["_one", "_two", "_this"]; params ["_three", "_four"]; };
AgentRev - c
Posted on Nov 01, 2021 - 16:00 (UTC)
Here's how to validate HashMap parameters:
_myHashMap = createHashMapFromArray [["a",1],["b",2],["c",3]]; [_myHashMap] call { params [["_theHashMap",createHashMap,[createHashMap]]]; };