%%% *************************************************************
%%% Copyright (C) 2004-2005 Torsten Anders (t.anders@qub.ac.uk) 
%%% This program is free software; you can redistribute it and/or
%%% modify it under the terms of the GNU General Public License
%%% as published by the Free Software Foundation; either version 2
%%% of the License, or (at your option) any later version.
%%% This program is distributed in the hope that it will be useful,
%%% but WITHOUT ANY WARRANTY; without even the implied warranty of
%%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%%% GNU General Public License for more details.
%%% *************************************************************

/** %% This functor defines means to specify lists of floats. Fenv stands for 'function envelopes': the idea is to define envelopes by numeric functions.
%%
%% NB: this functor is a stub. Extensions to transform and combine numerical functions as well as means to plot them are planned (see my func-env and plot Lisp packages).
%% */

functor
import   
   LUtils at 'x-ozlib://anders/strasheela/ListUtils.ozf'
   
export
   
   SampleFun SampleFun01

   MakeConstantFun
   Scale ScaleFun ScaleFun01 % ScaleList
   
   FullSinoid HalveSinoid Triangle
   
define

   %%
   %% 'outputting' functions: sampling into lists
   %%

   /** %% SampleFun samples the unary numerical function Fn. SampleFun returns a list of length N with the y-values of Fn for the N evenly spaced x-values in the interval [Min, Max]. Fn expects and returns a float, N is an integer, Min and Max are Floats
   %% */
   fun {SampleFun Fn N Min Max}
      %% this for loop buggy: length of list returned by Fenv.sampleFun for some even Ns to small -- typical float-precision problem
%       StepSize = (Max-Min) / {IntToFloat N-1}
%    in
%       for I in (Min; I=<Max; I+StepSize)
% 	 collect:C
%       do {C {Fn I}}
%       end
      StepSize = (Max-Min) / {IntToFloat N-1}
      Xs = {LUtils.arithmeticSeries Min StepSize N}
   in
      {Map Xs Fn}
   end
   /** %% SampleFun samples the unary numerical function Fn. SampleFun returns a list of length N with the y-values of Fn for the N evenly spaced x-values in the interval [0.0, 1.0]. Fn expects and returns a float, N is an integer.
   %% */
   fun {SampleFun01 Fn N}
      {SampleFun Fn N 0.0 1.0}
   end

   
   %%
   %% 'envelope' generators
   %%

   /** %% Returns a constant function which always returns Const.
   %% */
   fun {MakeConstantFun Const}
      fun {$ X}
	 Const
      end
   end

   
   %%
   %% Transforming functions
   %%
   
   /** %% Returns a value between NewMin and NewMax that is proportional to X between OldMin and OldMax. All arguments are floats.
   %% */
   %% ported from CM by Rick Taube
   fun {Scale X OldMin OldMax NewMin NewMax}
      ((NewMax - NewMin) / (OldMax - OldMin) * (X - OldMin)) + NewMin
   end
%    /** %% Scales the values in Xs (a list of floats) to values between NewMin and NewMax that are proportional to the respective value between OldMin and OldMax. OldMin, OldMax, NewMin, and NewMax are all floats.
%    %% */
%    %% !! shall I remove this again
%    fun {ScaleList Xs OldMin OldMax NewMin NewMax}
%       {Map Xs
%        fun {$ X}
% 	  {Scale X OldMin OldMax NewMin NewMax}
%        end}
%    end
   /** %% Returns a function which is a scaled version of Fn. Let X be the argument and Y be the result of the returned function: Y is between NewMin and NewMax and is proportional to X between OldMin and OldMax. Fn expects and returns a float; OldMin, OldMax, NewMin, and NewMax are all floats.
   %% */
   fun {ScaleFun Fn OldMin OldMax NewMin NewMax}
      fun {$ X}
	 {Scale {Fn X} OldMin OldMax NewMin NewMax}
      end
   end
   /** %% Returns a function which is a scaled version of Fn. Let X be the argument and Y be the result of the returned function: Y is between NewMin and NewMax and is proportional to X between 0.0 and 1.0. Fn expects and returns a float; NewMin, and NewMax are all floats.
   %% */
   fun {ScaleFun01 Fn NewMin NewMax}
      {ScaleFun Fn 0.0 1.0 NewMin NewMax}
   end


   
   %%
   %% example 'envelopes'
   %%

   /** %% Defines an arc-shaped function for X in [0.0, 1.0]. The function graph has the form of a whole period of a sinoid. The result is in [0.0, 1.0] with the maximum in the middle. X and the result are floats.
   %% */
   %% !!?? is this a hanning function?
   fun {FullSinoid X}
      Pi2 = 3.141592653589793 * 2.0
   in
      {Scale {Cos X*Pi2} 1.0 ~1.0 0.0 1.0}
   end

   /** %% Defines an arc-shaped function for X in [0.0, 1.0]. The function graph has the form of the halve period of a sin starting at 0. The result is in [0.0, 1.0] with the maximum in the middle. X and the result are floats.
   %% */
   %% !!?? is this a hanning function?
   fun {HalveSinoid X}
      Pi = 3.141592653589793 
   in
      {Sin X*Pi}
   end
   
   /** %% Defines an triangle-shaped function for X in [0.0, 1.0] (the shape of the function outside this interval is unspecified). The result is in [0.0, 1.0] with the maximum in the middle. X and the result are floats.
   %% */
   fun {Triangle X}
      if X < 0.5
      then X * 2.0
      else 2.0 - (X * 2.0)
      end
   end


   
end