%--------------------------------------------------------------------
\newpage
\section{Class \tkzClass{fct}}
\label{sec:class_fct}

The \tkzClass{fct} class represents a real-valued function
\[
x \longmapsto f(x)
\]
defined and evaluated in Lua. A \tkzClass{fct} object encapsulates either
(i) a numerical expression (given as a string in the variable \texttt{x}),
or (ii) a callable Lua function, together with methods for evaluation,
sampling, and geometric construction.

By convention, function objects are stored in a Lua table named
\tkzVar{fct}{F}. Although this name is not mandatory, using \texttt{F} is
strongly recommended for consistency across examples and documentation.
Each entry of \texttt{F} associates a symbolic name (such as \texttt{fa})
with an object of class \tkzClass{fct}. If a custom table name is used, it
must be initialized manually. The \tkzFct{tkz-elements}{init\_elements()}
function will reset the \texttt{F} table if it has already been defined.

\paragraph{Mathematical expressions.}
All expressions defining a \tkzClass{fct} object are evaluated using standard
Lua rules. A \tkzClass{fct} object can be evaluated at a real number, sampled on an
interval, converted into a \tkzClass{path} (for drawing with TikZ), or exported
to a data file.

\paragraph{Important.}
In function and parametric function definitions
(\tkzClass{fct} and \tkzClass{pfct}),
expressions must be written using standard mathematical notation.
The Lua prefix \texttt{math.} must \emph{not} be used.

In contrast, in all other methods and Lua code fragments of
\tkzNamePack{tkz-elements},
standard Lua syntax applies, and the use of the prefix \texttt{math.}
is required whenever a Lua mathematical function is called. For convenience, users may define local aliases in their Lua code, such as
\code{local sin, cos, pi = math.sin, math.cos, math.pi}.


\medskip
Correct:
\begin{verbatim}
sin(x), exp(-x^2)
\end{verbatim}

Incorrect (in \tkzClass{fct} and \tkzClass{pfct}):
\begin{verbatim}
math.sin(x), math.exp(-x^2)
\end{verbatim}

\subsection{Methods of the class fct}
The \tkzClass{fct} class offers a compact set of methods, centered around:
\emph{(i)} creating a function object, \emph{(ii)} evaluating it, and
\emph{(iii)} producing a \tkzClass{path} or a data file.

\vspace{1em}

\bgroup
\small
\captionof{table}{fct methods.}\label{fct:methods}
\begin{tabular}{ll}
\toprule
\texttt{Methods} & \texttt{Reference} \\
\midrule
\texttt{Creation} & \\
\midrule
\tkzFct{fct}{new(expr\_or\_fn)}   & [\ref{ssub:method_fct_new}] \\
\tkzFct{fct}{compile(expr)}      & [\ref{ssub:method_fct_compile}] \\
\midrule
\texttt{Reals / evaluation} & \\
\midrule
\tkzMeth{fct}{eval(x)}             & [\ref{ssub:method_fct_value}] \\
\midrule
\texttt{Points / Paths} & \\
\midrule
\tkzMeth{fct}{set\_scale(x)}     & [\ref{ssub:method_fct_set_scale}] \\
\tkzMeth{fct}{point(x)}     & [\ref{ssub:method_fct_point}] \\
\tkzMeth{fct}{path(xmin,xmax,n)}   & [\ref{ssub:method_fct_path}] \\
\bottomrule
\end{tabular}
\egroup
\label{ssub:method_fct_set_scale}
%-------------------- details ---------------------------------------
\subsubsection{Constructor \tkzFct{fct}{new(expr\_or\_fn)}}
\label{ssub:method_fct_new}

\texttt{Description: }Creates a function object from either a Lua expression
(string) or a callable Lua function. When a string is provided, it represents
an expression in the variable \texttt{x}, evaluated using standard Lua rules
(therefore requiring \texttt{math.} prefixes).

\medskip
\texttt{Arguments: }\par
\begin{itemize}
\item \code{expr\_or\_fn}: either
  \begin{itemize}
    \item a string representing an expression in \texttt{x}, or
    \item a callable Lua function \texttt{f(x)}.
  \end{itemize}
\end{itemize}

\medskip
\texttt{Returns: } a \tkzClass{fct} object.

\medskip
\texttt{Example: }
\begin{verbatim}
\directlua{
  init_elements()
  F.f = fct:new("x*math.exp(-x^2)+1")
  tex.print(F.f:value(0))
}
\end{verbatim}



\subsubsection{Function \tkzFct{fct}{compile(expr)}}
\label{ssub:method_fct_compile}

\texttt{Description: }Compiles an expression and returns a callable Lua function
(or wraps it into a \tkzClass{fct}, depending on the implementation). This is a
low-level helper mainly intended for internal use.

\medskip
\texttt{Argument: } \code{expr} (string, expression in variable \texttt{x}). \qquad

\medskip
\texttt{Returns: } a callable function or a \tkzClass{fct} object (depending on implementation).

\subsubsection{Method \tkzMeth{fct}{eval(x)}}
\label{ssub:method_fct_value}

\texttt{Description: }Evaluates the function at the real number \code{x}.

\medskip
\texttt{Returns: } a number (which may be \texttt{nan} or infinite if the expression is not defined).

\begin{verbatim}
  init_elements()
  F.fa = fct("sin(x) + x")
  PA.curve = F.fa:path(-2, 5, 200)
  z.A = F.fa:point(1.3)
  tex.print(F.fa:eval(math.pi/2))
\end{verbatim}


\subsubsection{Method \tkzMeth{fct}{point(x)}}
\label{ssub:method_fct_point}

\texttt{Description: }Constructs the point $(x,f(x))$ associated with the function.
This method provides a direct bridge between numerical evaluation and geometric
construction.

\medskip
\texttt{Returns: } a \tkzClass{point}.

\medskip
\texttt{Example: }
\begin{verbatim}
  init_elements()
  F.fa = fct("sin(x)+x")
  PA.curve = F.fa:path(-2, 5, 200)
  z.A = F.fa:point(1.5)
  % or z.A = point(1.3, F.fa:eval(1.3) )
\end{verbatim}

\subsubsection{Method \tkzMeth{fct}{path(xmin,xmax,n)}}
\label{ssub:method_fct_path}

\texttt{Description: }Samples the function on $[xmin,xmax]$ using \code{n}
subdivisions and returns a \tkzClass{path}. Invalid values are skipped (depending
on the internal policy).

\medskip
\texttt{Returns: } a \tkzClass{path}.

\medskip
\texttt{Example: }

\begin{tkzexample}[latex=.5\textwidth]
\directlua{
  init_elements()
  F.fa = fct("sin(x) + x")
  PA.curve = F.fa:path(-1, 5, 200)
  z.A = F.fa:point(math.pi/2)
}
\begin{tikzpicture}[scale=.75,gridded]
  \tkzInit[xmin=-1,xmax=5,ymin=-1,ymax=2]
  \tkzDrawX\tkzDrawY
  \tkzGetNodes
  \tkzDrawCoordinates[smooth,blue,thick](PA.curve)
  \tkzDrawPoint[red](A)
%  \tkzDrawPointsOnGraph[blue]{0,1,2}{fa}
%  \tkzDrawPointOnGraph[red]{-1}{fa}
\end{tikzpicture}
\end{tkzexample}

%

% ------------------------------------------------------------
% fct : set_scale
% ------------------------------------------------------------

\subsubsection{Method \tkzMeth{fct}{set\_scale}}
\label{ssub:method_fct_set_scale}

This method applies an anisotropic scaling to the function graph.

\medskip
\texttt{Syntax: }
\begin{quote}
F:set\_scale(sx, sy)
\end{quote}

\medskip
\texttt{Arguments: }
\begin{itemize}
\item \texttt{sx}: scaling factor applied to the $x$-coordinate.
\item \texttt{sy}: scaling factor applied to the $y$-coordinate.
\end{itemize}

\medskip
\texttt{Description: }

Let $f(x)$ be the original function.
After applying \texttt{set\_scale(sx, sy)}, a generated point

\[
(x, f(x))
\]

becomes

\[
(s_x x,\; s_y f(x)).
\]

The scaling affects the geometric output produced by
\texttt{point(x)} and \texttt{path(xmin, xmax, n)}.

The analytic expression of the function remains unchanged.

\medskip
\texttt{Example: }

\begin{tkzexample}[vbox]
\directlua{
  init_elements()
  F.f73 = fct("(1./90000)*x*x*x-(1./100)*x*x+(113./36)*x")
            :set_scale(1/100, 1/400)
  PA.scaled = F.f73:path(0, 800, 200)
  z.A  = F.f73:point(600)
  z.Pl, z.Pr = F.f73:tangent(600)
}
\begin{center}
\begin{tikzpicture}[scale=1.75]
\tkzGetNodes
\tkzInit[xmin=0,xmax=800,xstep=100,
         ymin=0,ymax=2000,ystep=400]
\tkzGrid
\tkzAxeXY
\tkzDrawCoordinates[smooth,red](PA.scaled)
\tkzDrawPoint[red,size=4](A)
\tkzDrawLine[blue,add = .5 and .5](Pl,Pr)
\end{tikzpicture}
\end{center}
\end{tkzexample}




\subsubsection{Method \tkzMeth{fct}{tangent(x0,<h>,<tol>)}}
\label{ssub:fct_tangent}

This method returns two points defining the tangent at abscissa \texttt{x0}.
If the curve behaves regularly at \texttt{x0}, a single tangent is returned.
If the curve has a corner (left and right slopes significantly different),
the method returns the two half-tangent points.

\medskip

\texttt{Arguments: }
\begin{itemize}
\item \texttt{x0}: abscissa where the tangent is evaluated.
\item \texttt{h} (optional): finite difference step passed to \texttt{half\_tangents}.
\item \texttt{tol} (optional): tolerance used to decide whether left/right slopes
define a unique tangent. Default: \texttt{1e-3}.
\end{itemize}

\medskip

\texttt{Returns: }
Two points \texttt{P1}, \texttt{P2} that define a tangent direction.
They are constructed at unit distance from the point $P=(x0,f(x0))$.

\medskip

\texttt{Behaviour: }

\begin{itemize}
  \item If the function is locally smooth at $x_0$
        (i.e.\ the left and right slopes are sufficiently close),
        a single tangent direction is computed using a centered derivative.
  \item If the slopes differ significantly (e.g.\ cusp or angle),
        the two half-tangents are returned.
\end{itemize}

\medskip

\texttt{Example: }

\begin{tkzexample}[vbox]
\directlua{
  init_elements()
  F.f691 = fct("x*exp(x)")
  PA.curve = F.f691:path(-5, 1, 200)
  PA.from = path:new()
  PA.to   = path:new()
  for x=-4, 1, 0.5 do
    local Pl, Pr = F.f691:tangent(x)
    PA.from:add_point(Pl)
    PA.to:add_point(Pr)
  end}

\begin{center}
 \begin{tikzpicture}[scale=2]
\tkzGetNodes
\tikzstyle{tan style}=[-]
\tkzInit[xmin=-5,xmax=2,ymin=-1,ymax=3]
\tkzDrawXY
\tkzDrawCoordinates[smooth,red](PA.curve)
\tkzText[draw,color = red,
     fill = orange!20](1.5,1.5){$y = xe^x$}
\tkzDrawSegmentsFromPaths[draw,color=blue,
  line width=.4pt,add=.5 and .5](PA.from,PA.to)
\end{tikzpicture}
\end{center}

\end{tkzexample}


% ------------------------------------------------------------
% fct : half_tangents
% ------------------------------------------------------------

\subsubsection{Method \tkzMeth{fct}{half\_tangents}}
\label{ssub:method_fct_half_tangents}

This method computes two half-tangent directions at abscissa \texttt{x0}
using a finite difference approximation.
It is mainly intended to provide two points defining the two possible tangent
directions when the curve has a corner or a cusp.

\texttt{Syntax: }
\begin{quote}
Pl, Pr, ml, mr = F:half\_tangents(x0, h)
\end{quote}

\texttt{Arguments: }
\begin{itemize}
\item \texttt{x0}: abscissa where the tangent directions are evaluated.
\item \texttt{h} (optional): finite difference step. If omitted, a default value
is chosen (relative to \texttt{x0}).
\end{itemize}

\texttt{Returns: }
\begin{itemize}
\item \texttt{Pl}, \texttt{Pr}: two points on the left and right tangent directions.
They are constructed at unit distance from the point $P=(x0,f(x0))$.
\item \texttt{ml}, \texttt{mr}: the corresponding left and right slopes.
\end{itemize}

\texttt{Description: }

Let $P=(x_0,f(x_0))$. The method evaluates
$P_+=(x_0+h,f(x_0+h))$ and $P_-=(x_0-h,f(x_0-h))$ and computes the slopes

\[
m_r=\frac{f(x_0+h)-f(x_0)}{(x_0+h)-x_0}, \qquad
m_l=\frac{f(x_0)-f(x_0-h)}{x_0-(x_0-h)}.
\]

Then it returns two points on the corresponding directions (left/right),
normalized so that $\overline{PPl}=\overline{PPr}=1$.

\texttt{Example: }

\begin{tkzexample}[vbox]
\directlua{
init_elements()
  F.f67 = fct("(exp(x)-1)/(exp(1)-1)"):set_scale(10, 10)
  PA.scaled = F.f67:path(0, 1, 200)
  z.P0l, z.P0r = F.f67:half_tangents(0)
  z.P1l, z.P1r = F.f67:half_tangents(1)
  z.P0 = F.f67:point(0)
  z.P1 = F.f67:point(1)
}

\begin{center}
\begin{tikzpicture}[scale=1.25]
\tkzGetNodes
\tkzInit[xmax=1,ymax=1,xstep=0.1,ystep=0.1]
\tkzGrid(0,0)(1,1)
\tkzAxeXY
\tkzDrawCoordinates[smooth,red,thick](PA.scaled)
 \tkzText[draw,color = red,fill = orange!20](0.5,0.6)%
{$f(x)=\dfrac{\text{e}^x-1}{\text{e}-1}$}
\tkzDrawSegments[>=stealth,->,cyan, thick, add = 0 and 4](P0,P0r P1,P1l)
\end{tikzpicture}
\end{center}
\end{tkzexample}[vbox]
\endinput