diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/datatool/datatool-user.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/datatool/datatool-user.tex | 87 |
1 files changed, 78 insertions, 9 deletions
diff --git a/Master/texmf-dist/doc/latex/datatool/datatool-user.tex b/Master/texmf-dist/doc/latex/datatool/datatool-user.tex index aeefbfea21a..08f01e258ff 100644 --- a/Master/texmf-dist/doc/latex/datatool/datatool-user.tex +++ b/Master/texmf-dist/doc/latex/datatool/datatool-user.tex @@ -103,11 +103,11 @@ \MakeShortVerb{"} - \title{User Manual for datatool bundle version~2.30} + \title{User Manual for datatool bundle version~2.31} \author{Nicola L.C. Talbot\\ \url{http://www.dickimaw-books.com/}} - \date{2018-04-16} + \date{2018-12-07} \maketitle \pagenumbering{roman} @@ -122,7 +122,7 @@ The \styfmt{datatool} bundle comes with the following documentation: \item[\url{datatool-code.pdf}] Advanced users wishing to know more about the inner workings of all the packages provided in the \styfmt{datatool} bundle should - read \qt{Documented Code for datatool v2.30} + read \qt{Documented Code for datatool v2.31} \item[INSTALL] Installation instructions. @@ -148,7 +148,7 @@ your calculations or data manipulation and save the results in a file that can be input into your document.} For large amounts of data that need to be sorted or filtered or joined, consider storing your data in an~SQL database and use -\app{datatooltk}\footnote{\url{http://www.dickimaw-books.com/apps/datatooltk/}} to import the data, +\app{datatooltk}\footnote{\url{http://www.dickimaw-books.com/software/datatooltk/}} to import the data, using SQL syntax to filter, sort and otherwise manipulate the values. \end{important} @@ -2069,7 +2069,7 @@ by \styfmt{datatool-base}). In addition to those commands, \styfmt{datatool-base} provides some commands that deal with comma-separated lists. Note that this just refers to a control sequence that stores -a list of elements separated by commands, for example: +a list of elements separated by commas, for example: \begin{verbatim} \newcommand{\mylist}{elephant,ant,zebra,duck} \end{verbatim} @@ -2083,16 +2083,40 @@ Formats the comma-separated list. The unstarred version scopes the internal operation. The starred form doesn't. The \meta{list} may either be an explicit comma-separated list or a control sequence whose replacement -text is a comma-separated list. For example: +text is a comma-separated list. If the list contains empty +elements then \cs{DTLformatlist} will either include or +skip the empty element according to the conditional: +\begin{definition}[\DescribeMacro{\ifDTLlistskipempty}] +\cs{ifDTLlistskipempty} +\end{definition} +For example: \begin{verbatim} -\newcommand{\mylist}{elephant,ant,zebra,duck}% +\newcommand{\mylist}{elephant,,ant,zebra,duck}% +\DTLlistskipemptytrue +\DTLformatlist{\mylist}\par +\DTLlistskipemptyfalse \DTLformatlist{\mylist} \end{verbatim} which produces: \begin{display} -\newcommand{\mylist}{elephant,ant,zebra,duck}% +\newcommand{\mylist}{elephant,,ant,zebra,duck}% +\DTLlistskipemptytrue +\DTLformatlist{\mylist}\par +\DTLlistskipemptyfalse \DTLformatlist{\mylist} \end{display} +The default setting is +\begin{verbatim} +\DTLlistskipemptytrue +\end{verbatim} +Note that this may cause a difference when upgrading to v2.31 +as in previous versions \cs{DTLformatlist} didn't skip empty +elements. To restore the original behaviour use: +\begin{verbatim} +\DTLlistskipemptyfalse +\end{verbatim} +before \cs{DTLformatlist}. + The list formatting command inserts \begin{definition}[\DescribeMacro\DTLlistformatsep] \cs{DTLlistformatsep} @@ -2166,8 +2190,53 @@ expansion on \meta{element}.) \begin{definition}[\DescribeMacro{\DTLnumitemsinlist}] \cs{DTLnumitemsinlist}\marg{list}\marg{cmd} \end{definition} -Counts the number of non-empty elements in \meta{list} and stores +Counts the number of elements in \meta{list} and stores the result in \meta{cmd}, which must be a control sequence. +As from v2.31, this obeys the conditional \cs{ifDTLlistskipempty} +to determine if empty elements should be skipped. For example: +\begin{verbatim} +\newcommand{\mylist}{foo,,bar,baz,wibble} +Number of non-empty elements: +\DTLnumitemsinlist{\mylist}{\listnum}\listnum.\par +\DTLlistskipemptyfalse +Number of elements (including empty): +\DTLnumitemsinlist{\mylist}{\listnum}\listnum. +\end{verbatim} +This produces: +\begin{display} +\newcommand{\mylist}{foo,,bar,baz,wibble} +Number of non-empty elements: \DTLnumitemsinlist{\mylist}{\listnum}\listnum.\par +\DTLlistskipemptyfalse +Number of elements (including empty): \DTLnumitemsinlist{\mylist}{\listnum}\listnum. +\end{display} + +\begin{definition}[\DescribeMacro{\DTLlistelement}] +\cs{DTLlistelement}\marg{list}\marg{index} +\end{definition} +Does the \meta{index}th element of the list (starting at 1 for +the first element) or generates a warning if the index is out +of range. This obeys the conditional \cs{ifDTLlistskipempty} +to determine if empty elements should be skipped. +For example: +\begin{verbatim} +\newcommand{\mylist}{foo,,bar,baz,wibble} +3rd item in list (skip empty): \DTLlistelement{\mylist}{3}.\par +\ifDTLlistskipempty +3rd item in list (include empty): \DTLlistelement{\mylist}{3}. +\end{verbatim} +This produces: +\begin{display} +\newcommand{\mylist}{foo,,bar,baz,wibble} +3rd item in list (skip empty): \DTLlistelement{\mylist}{3}.\par +\ifDTLlistskipempty +3rd item in list (include empty): \DTLlistelement{\mylist}{3}. +\end{display} + +\begin{definition}[\DescribeMacro{\DTLfetchlistelement}] +\cs{DTLfetchlistelement}\marg{list}\marg{index}\marg{cs} +\end{definition} +Like \cs{DTLlistelement} but it stores the \meta{index}th +element in the command given by \meta{cs}. \begin{definition}[\DescribeMacro\dtlsortlist] \cs{dtlsortlist}\marg{list cs}\marg{criteria cs} |