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 } )