%% $Id: pst-tools-doc.tex 607 2017-10-02 17:56:55Z herbert $
\documentclass[11pt,english,BCOR10mm,DIV12,bibliography=totoc,parskip=false,
   smallheadings, headexclude,footexclude,oneside]{pst-doc}
\usepackage[utf8]{inputenc}
\usepackage{pst-tools}
\let\pstToolsFV\fileversion
\usepackage{xltabular}
\usepackage{pst-plot}
\renewcommand\bgImage{}

\lstset{language=PSTricks,
    morekeywords={psPrintValue},basicstyle=\footnotesize\ttfamily}
%
\usepackage{biblatex}
\addbibresource{pst-tools-doc.bib}
\begin{document}

\title{\texttt{pst-tools}}
\subtitle{Helper functions; v.\pstToolsFV}
\author{Herbert Voß}
\docauthor{}
\date{\today}
\maketitle

\tableofcontents
\psset{unit=1cm}


\section{Predefined styles}

The style \Lkeyword{mmpaper} is defined for \Lcs{psgrid}:
%\newpsstyle{mmpaper}{subgriddiv=5,gridlabels=0,gridwidth=1pt,gridcolor=orange,subgridwidth=0.1pt,subgridcolor=orange!90}

\begin{LTXexample}[width=0.5\linewidth,frame=,pos=r]
\begin{pspicture}(6,3)
\psgrid[style=mmpaper](6,3)
\end{pspicture}

\begin{pspicture}(6,3)
\psgrid[style=mmpaper,
  gridcolor=blue,subgridcolor=blue!80](6,3)
\end{pspicture}
\end{LTXexample}


\section{\Lcs{psPrintValue}}\label{sec:printValue}
This macro allows to \Index{print} single values of a math function. It has the syntax

\begin{BDef}
\Lcs{psPrintValue}\OptArgs\Largb{PostScript code}\\
\Lcs{psPrintValue}\OptArg{algebraic,\ldots}\Largb{x value, algebraic code}
\end{BDef}

Important is the fact, that \Lcs{psPrintValue} works on \PS\ side. For \TeX\ it is only a box of
zero dimension. This is the reason why you have to put it into a box, which reserves horizontal
space.

There are the following valid options for \Lcs{psPrintValue}:

\noindent\medskip
\begin{xltabular}{\linewidth}{@{}l|>{\ttfamily}l>{\ttfamily}lX@{}}
\textrm{name} & \textrm{value}  & \textrm{default}\\\hline
\endhead
\Lkeyword{PSfont}        & PS font name & Times & only valid \PS\ font names are possible, e.g. 
    \Lps{Times-Roman}, \Lps{Helvetica}, \Lps{Courier}, \Lps{Helvetica}, \Lps{Bookman}. If you want to embed the fonts
    use always the URW names NimbusRomNo9L-Regu, NimbusSanL-Regu and  NimbusMonL-Regu. However, the names
may vary on different operating systems.\\
\Lkeyword{postString} & <string>     & \{\}     & will be appended to the number string\\
\Lkeyword{trimSpaces} & <boolean>     & false     & will strip spaces on the right\\
\Lkeyword{fontscale} & <number>     & 10     & the font scale in pt\\
\Lkeyword{valuewidth} & <number>     & 10     & the width of the string for the converted 
    real number; if it is too small, no value is printed\\
\Lkeyword{decimals}  & <number>     & -1     & the number of printed decimals, a negative value
    prints all possible digits.\\ 
\Lkeyword{xShift}  & <number>     & 0     & the x shift in pt for the output, relative to the current point.\\ 
\Lkeyword{algebraic}  & <boolean>     & false     & function in algebraic notation.\\ 
\Lkeyword{VarName} & <string> & \{\} & saves the value in /<VarName> for further use\\
\Lkeyword{comma}  & <boolean>     & false     & comma instead of the dor for decimals\\ 
\end{xltabular}

\begin{center}
\psset{fontscale=12}
\makebox[2em]{x(deg)} \makebox[5em]{$\sin x$} \makebox[4em]{$\cos x$}\hspace{1em}
\makebox[5em]{$\sqrt x$}\makebox[7em]{$\sin x+\cos x$}\makebox[6em]{$\sin^2 x+\cos^2 x$}\\[3pt]
\multido{\iA=0+10}{18}{
  \makebox[1em]{\iA}
  \makebox[5em]{\psPrintValue[PSfont=NimbusRomNo9L-Regu,xShift=-10]{\iA\space sin}}
  \makebox[4em][r]{\psPrintValue[PSfont=NimbusMonL-Regu,fontscale=10,decimals=3,xShift=-20]{\iA\space cos}}\hspace{1em}
  \makebox[5em]{\psPrintValue[valuewidth=15,linecolor=blue,PSfont=NimbusSanL-Regu]{\iA\space sqrt}}
  \makebox[7em]{\psPrintValue[comma,PSfont=NimbusRomNo9L-ReguItal]{\iA\space dup sin exch cos add}}
  \makebox[6em]{\psPrintValue[PSfont=Palatino-Roman]{\iA\space dup sin dup mul exch cos dup mul add}}\\}
\end{center}

\bigskip

\begin{lstlisting}
\psset{fontscale=12}
\makebox[2em]{x(deg)} \makebox[5em]{$\sin x$} \makebox[4em]{$\cos x$}\hspace{1em}
\makebox[5em]{$\sqrt x$}\makebox[7em]{$\sin x+\cos x$}\makebox[6em]{$\sin^2 x+\cos^2 x$}\\[3pt]
\multido{\iA=0+10}{18}{
  \makebox[1em]{\iA}
  \makebox[5em]{\psPrintValue[PSfont=NimbusRomNo9L-Regu,xShift=-10]{\iA\space sin}}
  \makebox[4em][r]{\psPrintValue[PSfont=NimbusMonL-Regu,fontscale=10,decimals=3,xShift=-20]{\iA\space cos}}\hspace{1em}
  \makebox[5em]{\psPrintValue[valuewidth=15,linecolor=blue,PSfont=NimbusSanL-Regu]{\iA\space sqrt}}
  \makebox[7em]{\psPrintValue[comma,PSfont=NimbusRomNo9L-ReguItal]{\iA\space dup sin exch cos add}}
  \makebox[6em]{\psPrintValue[PSfont=Palatino-Roman]{\iA\space dup sin dup mul exch cos dup mul add}}\\}
\end{lstlisting}

With enabled \Lkeyword{algebraic} option there must be two arguments, separated by a comma.
The first one is the x value as a number, which can also be PostScript code, which leaves a
number on the stack. The second part is the function described in algebraic notation.
Pay attention, in algebraic notation angles must be in radian and not degrees.

\begin{center}
\psset{algebraic, fontscale=12}% All functions now in algebraic notation
\makebox[2em]{x(deg)} \makebox[5em]{$\sin x$} \makebox[4em]{$\cos x$}\hspace{1em}
\makebox[5em]{$\sqrt x$}\makebox[7em]{$\sin x+\cos x$}\makebox[6em]{$\sin^2 x+\cos^2 x$}\\[3pt]
\multido{\rA=0+0.1}{18}{\makebox[1em]{\rA}
  \makebox[5em]{\psPrintValue[PSfont=NimbusSanL-Regu,xShift=-10]{\rA, sin(x)}}
  \makebox[4em][r]{\psPrintValue[PSfont=NimbusMonL-Regu,fontscale=10,decimals=3,xShift=-20]{\rA,cos(x)}}\hspace{1em}
  \makebox[5em]{\psPrintValue[valuewidth=15,linecolor=blue,PSfont=NimbusSanL-Regu]{\rA,sqrt(x)}}
  \makebox[7em]{\psPrintValue[comma,PSfont=NimbusRomNo9L-ReguItal]{\rA,sin(x)+cos(x)}}
  \makebox[6em]{\psPrintValue[PSfont=Palatino-Roman]{\rA,sin(x)^2+cos(x)^2}}\\}
\end{center}

\bigskip

\begin{lstlisting}
\psset{algebraic, fontscale=12}% All functions now in algebraic notation
\makebox[2em]{x(deg)} \makebox[5em]{$\sin x$} \makebox[4em]{$\cos x$}\hspace{1em}
\makebox[5em]{$\sqrt x$}\makebox[7em]{$\sin x+\cos x$}\makebox[6em]{$\sin^2 x+\cos^2 x$}\\[3pt]
\multido{\rA=0+0.1}{18}{\makebox[1em]{\rA}
  \makebox[5em]{\psPrintValue[PSfont=NimbusSanL-Regu,xShift=-10]{\rA, sin(x)}}
  \makebox[4em][r]{\psPrintValue[PSfont=NimbusMonL-Regu,fontscale=10,decimals=3,xShift=-20]{\rA,cos(x)}}\hspace{1em}
  \makebox[5em]{\psPrintValue[valuewidth=15,linecolor=blue,PSfont=NimbusSanL-Regu]{\rA,sqrt(x)}}
  \makebox[7em]{\psPrintValue[comma,PSfont=NimbusRomNo9L-ReguItal]{\rA,sin(x)+cos(x)}}
  \makebox[6em]{\psPrintValue[PSfont=Palatino-Roman]{\rA,sin(x)^2+cos(x)^2}}\\}
\end{lstlisting}



\begin{center}
foo \makebox[2em][l]{\psPrintValue[comma]{3.14 10 mul round 10 div}}bar\\[3pt]
foo \makebox[2em][l]{\psPrintValue[comma,PSfont=StandardSymL,
  postString=\string\260]{3.14 10 mul round 10 div}}bar\\[3pt]
foo \makebox[3.5em][l]{\psPrintValue[PSfont=StandardSymL,decimals=6,
  postString=\string\260]{3.14 dup mul}}bar
\end{center}

\bigskip

\begin{lstlisting}
foo \makebox[2em][l]{\psPrintValue[comma]{3.14 10 mul round 10 div}}bar\\[3pt]
foo \makebox[2em][l]{\psPrintValue[comma,PSfont=StandardSymL,
  postString=\string\260]{3.14 10 mul round 10 div}}bar\\[3pt]
foo \makebox[3.5em][l]{\psPrintValue[PSfont=StandardSymL,decimals=6,
  postString=\string\260]{3.14 dup mul}}bar
\end{lstlisting}



\section{\nxLcs{psGetElement}}\label{sec:getElement}
The macro returns the n-th Element of a comma separated list into the 
user definied Macro \Lcs{\Larga{Element}}.

\begin{BDef}
\Lcs{psGetElement}\Largb{Index}\Largb{value list}\nxLcs{\Larga{Element}}\\
\end{BDef}


\begin{lstlisting}
\def\ColorList{,violet,blue,green,red}% Index starts at 0
\begin{pspicture}(-7,-4)(7,5)
\psaxes(0,0)(-6.5,-4)(6.5,5)
\psset{plotpoints=400,algebraic}
\psforeach{\iA}{1,2,3,4}{%
  \psGetElement{\iA}{\ColorList}\foo
  \psplot[linecolor=\foo]{-6.28}{6.28}{\iA*sin(\iA*x)}}
\end{pspicture}
\end{lstlisting}

\def\ColorList{,violet,blue,green,red}% Index starts at 0
\begin{pspicture}(-7,-4)(7,5)
\psaxes(0,0)(-6.5,-4)(6.5,5)
\psset{plotpoints=400,algebraic}
\psforeach{\iA}{1,2,3,4}{%
  \psGetElement{\iA}{\ColorList}\foo
  \psplot[linecolor=\foo]{-6.28}{6.28}{\iA*sin(\iA*x)}}
\end{pspicture}








\clearpage
\section{List of all optional arguments for \texttt{pst-tools}}

\xkvview{family=pst-tools,columns={key,type,default}}




\bgroup
\raggedright
\nocite{*}
%\bibliographystyle{plain}
\printbibliography
\egroup

\printindex



\end{document}

\def\psGetElement#1#2{% #1 natural number; #2 comma separated list
	\pst@cnto=0\relax
	\pst@cntp=#1\relax
	\expandafter\psGetElement@i#2,,\@nil
}
\iftrue
\def\psGetElement@i#1,#2,#3\@nil{%
	\ifnum\the\pst@cnto<\pst@cntp\relax
 	  \advance\pst@cnto by \@ne 
      \def\ps@next{\psGetElement@i#2,#3\@nil}%
	\else 
	  \def\ps@next{#1}%
	\fi
	\ps@next
}
