Difference between revisions of "MultiResult"

Latest revision as of 21:49, 5 February 2025

Multiresult lets a User-Defined Function or expression return more than one distinct value. It is also convenient in some loops when you want to set multiple local variables at the same time.

MultiResult( expr ... )

_( expr ... )

These two equivalent functions accept repeated expressions separated by commas. It evaluates the only the ones that are captured by the caller or parent expression, and returns the results as multiple distinct return values. The dimensions of each return value are kept distinct -- they are not combined in any way as they would in other functions. MultiResult(a,b,c) and _(a,b,c) are identical in functionality. Stylistically, the MultiResult(...) syntax is generally nicer when used for a UDF return value, and the _(...) notation lends itself to looping constructs.

Examples

This function returns the R, G, B and Alpha components as separate results given a color integer c.

Function ColorComponents(c: Color ) :=
MultiResult(
BitAnd( [ BitShift( c, 16), 0xFF] ),
BitAnd( [ BitShift( c, 8), 0xFF] ),
BitAnd( [ c, 0xFF] ),
BitAnd( [ BitShift( c, 24), 0xFF] ) )

You can then capture the separate return values in local values using, e.g.,

Local (r,g,b,a) := ColorComponents( 'Turquoise' );

When you don't need the alpha value,

Local (r,g,b) := ColorComponents( 'Turquoise' );

In this case, the final expression BitAnd( [ BitShift( c, 24), 0xFF] ) in the UDF does not get evaluated.

The next example illustrates its use in a looping construct. Here v is indexed by Time and In1, but the «bodyExpr» does something where it requires v to be indexed only by Time. At the same time, it also needs to know the corresponding index value from In1 for that slice of v.

Local ( vi[Time], i[ ] ) := _( v, In1);

«bodyExpr»

History

Added in release 5.2.

@@ Line 1: / Line 1: @@
-''new to [[Analytica 5.2]]''
+Multiresult lets a [[User-Defined Function]] or expression return more than one distinct value.  It is also convenient in some loops when you want to set multiple local variables at the same time.
-Use this function when you want to return more than one distinct value from a [[User-Defined Function]] or expression.  It is also sometimes convenient it certain looping scenarios when you want to set multiple local variables at the same time.
 == MultiResult( expr ... ) ==
 == _( expr ... ) ==
-Accepts repeated expressions separated by commas, evaluates the only the ones that are captured by the caller or parent expression, and returns the results as multiple distinct return values. The dimensions of each return value are kept distinct -- they are not combined in any way.  <code>MultiResult(a,b,c)</code> and <code>_(a,b,c)</code> are identical in functionality.  Stylistically, the <code>MultiResult(...)</code> syntax is generally nicer when used for a UDF return value, whereas the <code>_(...)</code> lends itself to looping scenarios.
+These two equivalent functions accept repeated expressions separated by commas. It evaluates the only the ones that are captured by the caller or parent expression, and returns the results as multiple distinct return values. The dimensions of each return value are kept distinct -- they are not combined in any way as they would in other functions.  <code>MultiResult(a,b,c)</code> and <code>_(a,b,c)</code> are identical in functionality.  Stylistically, the <code>MultiResult(...)</code> syntax is generally nicer when used for a UDF return value, and the <code>_(...)</code> notation lends itself to looping constructs.
 === Examples ===
-The following function returns the R, G, B and Alpha components of a color integer, as separate return values.
+This function returns the R, G, B and Alpha components as separate results given a color integer c.
-:Function ColorComponents( c: Color ) := <code>
+<code>
-::MultiResult(
+:Function ColorComponents(c: Color ) :=
-:::BitAnd( [BitShift( c, 16), 0xFF] ),
+::[[MultiResult]](
-:::BitAnd( [BitShift( c, 8), 0xFF] ),
+:::[[BitAnd]]( [ [[BitShift]]( c, 16), 0xFF] ),
-:::BitAnd( [c, 0xFF] ),
+:::[[BitAnd]]( [ [[BitShift]]( c, 8), 0xFF] ),
-:::BitAnd( [BitShift( c, 24), 0xFF] ) )
+:::[[BitAnd]]( [ c, 0xFF] ),
-</code>
+:::[[BitAnd]]( [ [[BitShift]]( c, 24), 0xFF] ) )
+</code>You can then capture the separate return values in local values using, e.g.,
-A caller could then capture the separate return values in local values using, e.g.,
 :<code>[[Local]] (r,g,b,a) := ColorComponents( 'Turquoise' );</code>
+When you don't need the alpha value,
+:<code>[[Local]] (r,g,b) := ColorComponents( 'Turquoise' );</code>
+In this case, the final expression <code>[[BitAnd]]( [ [[BitShift]]( c, 24), 0xFF] )</code> in the UDF does not get evaluated.
-The next example illustrates its use in a looping construct.  Here <code>v</code> is indexed by <code>In1</code>, and the «bodyExpr» does something where it requires v to be atomic, but it also needs to know the corresponding index value for that slice of <code>v</code>.
+The next example illustrates its use in a looping construct.  Here <code>v</code> is indexed by <code>Time</code> and <code>In1</code>, but the «bodyExpr» does something where it requires <code>v</code> to be indexed only by <code>Time</code>.  At the same time, it also needs to know the corresponding index value from <code>In1</code> for that slice of <code>v</code>.
-:<code>[[Local]] ( vi, i ) := _( v, In1);</code>
+:<code>[[Local]] ( vi[Time], i[ ] ) := _( v, In1);</code>
 :''«bodyExpr»''
+== History ==
+Added in release 5.2.
 == See Also ==
 * [[Local]]
+* [[User-Defined Functions]]