Class JxnFunction

  • Direct Known Subclasses:
    JxnD, JxnF, JxnF2, JxnI, JxnL

    public class JxnFunction
    extends Object
    Parses, stores and executes a jxn function.
    Examples:
    
       ! Create a JxnFunction 'si' using a constructor:
       ! si = @JxnFunction( $this, "x", "sin x / x" )
       ! or equivalent using a lambda expression like syntax:
       si = @JxnFunction( $this, "x -> sin x / x" )
        = ( x ) -> sin x / x (JxnFunction)
    
       ! Call the function with arguments of different type:
       si( 1. )  ! argument type: double
        = 0.8414709848078965 (double)
       si( j )   ! argument type: JxnComplexAlgebra
        = 1.1752011936438014 + j 0.0 = 1.1752011936438014 <) 0.0° (JxnComplexAlgebra)   
       plot( x, si(x) );  ! argument type: JxnRealArrayAlgebra
    
    
       ! or create a JxnFunction 'factorial' using jxn special commands:
       #function factorial( n )  ! = 1 * 2 * 3 * ... * n
          $i = 1; $result = 1  ! local variables start with '$'
          #while le( $i, n )
             $result = $result * $i
             $i = $i + 1
          #endwhile
          #return $result
       #endfunction
    
       ! Call the function (Note: the return type adjusts!):
       factorial(5)
        = 120 (int)
       factorial(10)
        = 3628800 (int)
       factorial(20)
        = 2432902008176640000 (long)
       factorial(30)
        = 2.6525285981219103E32 (double)
    
        
       ! Create a function with 2 parameters:
       #function gcd( a, b )  ! greatest common divisor
          "gcd called with: a = " + a + ", b = " + b
          #if ne( b, 0 )
             #return gcd( b, a % b )  ! recursive call
          #else
             #return a
          #endif
       #endfunction
       
       gcd( 60,96 )
        = 12 (int)
    
       ! Activate debug logging for gcd:
       gcd.setDebug(3)
        = 0 (int)
       gcd( 24, 18 )
       : "gcd called with: a = " + a + ", b = " + b
       :  = gcd called with: a = 24, b = 18 (java.lang.String)
       : #if ne( b, 0 )
       : #return gcd( b, a % b )
       : "gcd called with: a = " + a + ", b = " + b
       :  = gcd called with: a = 18, b = 6 (java.lang.String)
       : #if ne( b, 0 )
       : #return gcd( b, a % b )
       : "gcd called with: a = " + a + ", b = " + b
       :  = gcd called with: a = 6, b = 0 (java.lang.String)
       : #if ne( b, 0 )
       : #else
       : #return a
        = 6 (int)
    
    
       ! Create and call a function with variable number of arguments available in the array parameter $_:
       sum = @JxnFunction( $this, "$result = 0; JxnLoop.foreach( $this, \"$_i\", $_, \"$result += $_i;\" )" )
        = ... -> $result = 0; JxnLoop.foreach( $this, "$_i", $_, "$result += $_i;" ) (JxnFunction)
       sum( 2, 3, 5, 7, 11 )
        = 28 (int)
       sum( 2.2, 3.3, 5.5 )
        = 11.0 (double)
        
       ! Create a function 'print' to show intermedeate values:
       print = @JxnFunction( $this, "join $_" )  ! or "o -> o" for a single argument
        = ... -> join $_ (JxnFunction)
       print.setDebug(1)  ! enable output
        = 0 (int)
       ! Usage: call e.g. print( "abc", j, PI ) from within a #function definition
     
    See Also:
    JxnScripting
    • Constructor Detail

      • JxnFunction

        protected JxnFunction​(JxnFunction f)
      • JxnFunction

        public JxnFunction​(String cmd)
        Deprecated.
        Use @JxnFunction( $this, cmd ).
      • JxnFunction

        public JxnFunction​(KmgFormelInterpreter fi,
                           String cmd)
        Defines a jxn function with variable number of arguments. cmd can access the arguments passed to the exec method via an array $_[0] … $_[n-1]. This constructor also allows a → lambda expression like syntax (with fixed number of arguments).

        Please note the difference:
          fx = @JxnFunction( $this, "cmd" ) ! arbitrary number of arguments for parameters in array $_[0] … $_[n-1]
          f0 = @JxnFunction( $this, "", "cmd" ) ! empty String: no argument expected => call f0()
          f2 = @JxnFunction( $this, "x, y", "cmd" ) ! requires fixed number (e.g. 2) of arguments for paramters  x, y
          or equivalent using lambda expression syntax:
          f2 = @JxnFunction( $this, "( x, y ) -> cmd" ) ! requires fixed number (e.g. 2) of arguments for paramters  x, y

        or using jxn special commands in a jxn script file:
          #function fx   ! no round brackets: allows arbitrary number of arguments passed to parameters in array  $_[0] … $_[n-1]
          #function f0() ! empty parenthesis: no argument expected => call f0()
          #function f4( a, b, c, d ) ! requires fixed number (e.g. 4) of arguments for parameters  a, b, c, d
        Parameters:
        cmd - statement_sequence (one or more statements separated by ';') .   (Note: jxn does not support blocks in braces {…} as possible in Java → lambda expressions)
        See Also:
        setArityLenience(int)
      • JxnFunction

        public JxnFunction​(KmgFormelInterpreter fi,
                           String parameterList,
                           String cmd)
        Defines a jxn function with fixed number of arguments. cmd can access the arguments passed to the exec method by the names passed to the construtor via parameterList and via an array $_[0] … $_[n-1]
        Parameters:
        parameterList - String containing the names of the parameters for use in cmd separated by '   ' or ','. If "" (empty String) is passed as argument, the function expects no parameters.
        cmd - statement_sequence (one or more statements separated by ';') .
        See Also:
        setArityLenience(int)
      • JxnFunction

        public JxnFunction​(KmgFormelInterpreter fi,
                           String[] parameterNames,
                           String cmd)
        Defines a jxn function with fixed number of arguments. cmd can access the arguments passed to the exec method by the names passed to the construtor via parameterNames and via an array $_[0] … $_[n-1]
        Parameters:
        parameterNames - array containing the names of the parameters for use in cmd.
        cmd - statement_sequence (one or more statements separated by ';') .
    • Method Detail

      • setShowInternalResults

        public boolean setShowInternalResults​(boolean show)
        Controls if to show internal results during function execution (for debug).
        Returns:
        old value
      • setShowConditional

        public boolean setShowConditional​(boolean show)
        Controls if to show conditional commands during function execution (for debug).
        Returns:
        old value
      • setArityLenience

        public int setArityLenience​(int arityLenience)
        Determines what to do if the number of arguments does not match the number of parameters.
        If arityLenience is not 0, a deviation of the number of arguments from the number of parameters is handled as follows:
        If mArgs > nParams surplus arguments can be accessed via the array $_[…].
        If mArgs < nParams the function must check the existence of the argument via #ifdef … (caution: if an argument does not exist the parameter no more masks a possible global variable of identical name)
        Parameters:
        arityLenience - 0: abort (default), 1: continue with warning, -1: silently ignore
        Returns:
        old value
      • getArityLenience

        public int getArityLenience()
        Returns arityLenience set for this function instance.
      • exec

        protected Object exec​(Object[] args)
        Maps args to $_ and the names passed to the constructor via parameterNames.
        Example:
          fn = @JxnFunction( … ) ! calls a constructor to create a function instance fn
            :
          fn( arg1, arg2, ..., argN ) ! ⇒ jxn internally calls fn.exec( { arg1, arg2, ..., argN } )