Usefulness of using an expandable command

Question

I would like to see how I can show the advantage of using an expandable command. I made the command \myDimensionCommand but I do not see it is the best way to show the advantages to use fully expandable command.

\documentclass{article}

\ExplSyntaxOff

\NewExpandableDocumentCommand {\convertto} {omm}
  {
    % #1 = number of decimal digits
    % #2 = length
    % #3 = new unit
    \IfNoValueTF {#1}
      {
        \fpeval{\dimeval{#2}/(1#3)}\,#3
      }
         {
           \fpeval{round(\dimeval{#2}/(1#3),#1)}\,#3
         }
  }

% Define a command that uses \convertto
\NewDocumentCommand{\myDimensionCommand}{m m}
  {
    The~converted~dimension~is:~\convertto{#1}{#2}{mm}.
  }

\ExplSyntaxOff

\begin{document}

\convertto[2]{34pt}{cm}

\end{document}

Answer 1

A difference can for example be demonstrated in the bookmarks:

\documentclass{article}

\ExplSyntaxOff

\NewExpandableDocumentCommand {\convertto} {omm}
  {
    % #1 = number of decimal digits
    % #2 = length
    % #3 = new unit
    \IfNoValueTF {#1}
      {
        \fpeval{\dimeval{#2}/(1#3)}\,#3
      }
         {
           \fpeval{round(\dimeval{#2}/(1#3),#1)}\,#3
         }
  }

\NewDocumentCommand {\xconvertto} {omm}
  {
    % #1 = number of decimal digits
    % #2 = length
    % #3 = new unit
    \IfNoValueTF {#1}
      {
        \fpeval{\dimeval{#2}/(1#3)}\,#3
      }
         {
           \fpeval{round(\dimeval{#2}/(1#3),#1)}\,#3
         }
  }


\ExplSyntaxOff
\usepackage{hyperref}
\begin{document}

\section{ Test: \convertto[2]{34pt}{cm}}

\section{ Test: \xconvertto[2]{34pt}{cm}}
\end{document}

This prints the same:

But the bookmarks look quite different:

Answer 2

The difference is that one is expandable and the other isn't, so inside an \edef for instance, one is fully expanded, the other isn't, you can use an expandable command inside other expressions whereas you can't use an unexpandable command there. So one is easier to nest in other code, the other requires you to set a macro with the result as part of your code, so that further code can use that macro to do additional steps on the result. Simple document illustrating the difference in behaviour in an \edef:

\documentclass{article}

\ExplSyntaxOn

\NewExpandableDocumentCommand \convertto { o m m }
  {
    % #1 = number of decimal digits
    % #2 = length
    % #3 = new unit
    \IfNoValueTF {#1}
      { \fpeval{\dimeval{#2}/(1#3)}\,#3 }
      { \fpeval{round(\dimeval{#2}/(1#3),#1)}\,#3 }
  }
\NewDocumentCommand \protectedconvertto { o m m }
  {
    % #1 = number of decimal digits
    % #2 = length
    % #3 = new unit
    \IfNoValueTF {#1}
      { \fpeval{\dimeval{#2}/(1#3)}\,#3 }
      { \fpeval{round(\dimeval{#2}/(1#3),#1)}\,#3 }
  }

\ExplSyntaxOff

\begin{document}
\ttfamily

\edef\foo{\convertto{2cm}{mm}}\meaning\foo

\edef\foo{\protectedconvertto{2cm}{mm}}\meaning\foo
\end{document}

Answer 3

It's not really a matter of advantage and disadvantage, as choosing a suitable definition, only you can do that. Also note you are adding lots of space from ends of lines in your definition as you are missing \ExplSyntaxOn

Here I use your definition in a protected command, as you had it and as an expandable command, and then use them both in an expansion context (\typeout) You get

\myDimensionCommandA {34pt}{cm}
The converted dimension is: 1.194963331949633\,cm{mm}.

so which command is advantageous depends on which output you need in the real context.

\documentclass{article}

\ExplSyntaxOn% ON!!!!!

\NewExpandableDocumentCommand {\convertto} {omm}
  {
    % #1 = number of decimal digits
    % #2 = length
    % #3 = new unit
    \IfNoValueTF {#1}
      {
        \fpeval{\dimeval{#2}/(1#3)}\,#3
      }
         {
           \fpeval{round(\dimeval{#2}/(1#3),#1)}\,#3
         }
  }

% Define a protected command that uses \convertto
\NewDocumentCommand{\myDimensionCommandA}{m m}
  {
    The~converted~dimension~is:~\convertto{#1}{#2}{mm}.
  }

% Define an expandable command that uses \convertto
\NewExpandableDocumentCommand{\myDimensionCommandB}{m m}
  {
    The~converted~dimension~is:~\convertto{#1}{#2}{mm}.
  }

\ExplSyntaxOff

\begin{document}



\typeout{\myDimensionCommandA{34pt}{cm}}

\typeout{\myDimensionCommandB{34pt}{cm}}

\end{document}

Note the second one here looks perhaps more readable but it only shows one part of its internal definition \, other commands may show many more internal implementation details that you would never want to show in such a context, so the choice of which style to use depends on the command and the context in which it is likely to be used.

Answer 4

In the example below, \testA is defined with \NewDocumentCommand and \testB is defined with \NewExpandableDocumentCommand. If used as an option to \draw then \testA{red} fails because \testA{red} is not recognized as a color. The option \testB{red} does work because \testB is defined with \NewExpandableDocumentCommand.

\documentclass[border=6pt]{standalone}
\usepackage{tikz}
\NewDocumentCommand\testA{m}{#1}
\NewExpandableDocumentCommand\testB{m}{#1}
\begin{document}
\begin{tikzpicture}
%\draw[\testA{red}] (0,0)--(1,1);%fails
\draw[\testB{red}] (0,0)--(1,1);%works
\end{tikzpicture}
\end{document}

Answer 5

Another scenario where expandability is useful is creating external text-files, e.g., comma-separated-value-lists/.csv-files holding contents of databases, that are to be processed by programs other than TeX which don't understand LaTeX sytax so that all control sequence tokens in the stuff to be written to external text file should go away via expansion.

The following example produces two .csv-files via the package datatool.

(The command \verbatiminput from the package verbatim is used so that you can see the content of these files within the pdf-file which results from compiling.)

The second of these files comes from entries where the non-expandable command is used, thus it contains things like \myDimensionCommand {2}{2.54cm} which you probably don't want in a .csv-file that is to be processed further by software other than LaTeX.

\documentclass{article}
\usepackage{datatool, verbatim}

% \ExplSyntaxOn
% \cs_new_eq:NN \fpeval \fp_eval:n
% \cs_new_eq:NN \dimeval \dim_eval:n
% \ExplSyntaxOff

\NewExpandableDocumentCommand {\convertto} {omm}
  {%%
    % #1 = number of decimal digits
    % #2 = length
    % #3 = new unit
    \IfNoValueTF {#1}
      {%%
        \fpeval{\dimeval{#2}/(1#3)}\,#3%%
      }
      {%%
        \fpeval{round(\dimeval{#2}/(1#3),#1)}\,#3%%
      }%%
  }

% Define a command that uses \convertto
\NewDocumentCommand{\myDimensionCommand}{m m}
  {%% The first argument of \convertto is optional and therefore
   %% must be in square brackets!!!
    The converted dimension is: \convertto[{#1}]{#2}{mm}.%%
  }

% Create .csv-files holding values of length quantities 
% expressed as multiples of different units:

\begingroup

\def\,{}% \convertto beneath other things delivers a
        % control symbol token \,  , which in turn in LaTeX
        % is defined as a protected/an unexpandable command
        % for producing a thin horizontal space (.16667em).
        % We want neither a thinspace nor the control sequence
        % \, to be written to text files, thus within a local
        % scope/a group redefine \, so that it just vanishes
        % when being expanded.

\DTLnewdb{Database}%
\DTLaddcolumn{Database}{ValueToConvert}%
\DTLsetheader{Database}{ValueToConvert}{dimension to convert}%
\DTLaddcolumn{Database}{ConversionResults}%
\DTLsetheader{Database}{ConversionResults}{result of conversion}%
\dtlexpandnewvalue
\DTLnewrow{Database}%
\DTLnewdbentry{Database}{ValueToConvert}{2.54cm}%
\DTLnewdbentry{Database}{ConversionResults}{\convertto[2]{2.54cm}{in}}%
\DTLnewrow{Database}%
\DTLnewdbentry{Database}{ValueToConvert}{65536sp}%
\DTLnewdbentry{Database}{ConversionResults}{\convertto[2]{65536sp}{pt}}%
\dtlnoexpandnewvalue
\DTLsavedb{Database}{Entriesxpanded.csv}%

\DTLcleardb{Database}%

\DTLaddcolumn{Database}{ValueToConvert}%
\DTLsetheader{Database}{ValueToConvert}{dimension to convert}%
\DTLaddcolumn{Database}{ConversionResults}%
\DTLsetheader{Database}{ConversionResults}{result of conversion}%
\dtlexpandnewvalue
\DTLnewrow{Database}%
\DTLnewdbentry{Database}{ValueToConvert}{2.54cm}%
\DTLnewdbentry{Database}{ConversionResults}{\myDimensionCommand{2}{2.54cm}}%
\DTLnewrow{Database}%
\DTLnewdbentry{Database}{ValueToConvert}{72bp}%
\DTLnewdbentry{Database}{ConversionResults}{\myDimensionCommand{2}{72bp}}%
\dtlnoexpandnewvalue
\DTLsavedb{Database}{Entriesunexpanded.csv}%

\DTLcleardb{Database}%

\endgroup

\begin{document}

% The content of the  .csv-files

Here is the content of the file "Entriesxpanded.csv" which holds entries coming from expandable commands:

\verbatiminput{Entriesxpanded.csv}

Here is the content of the file "Entriesunexpanded.csv" which holds entries coming from unexpandable commands:

\verbatiminput{Entriesunexpanded.csv}

\end{document}