\@ifstar ¶Synopsis:
\newcommand{\mycmd}{\@ifstar{\mycmd@star}{\mycmd@nostar}}
\newcommand{\mycmd@nostar}[nostar-num-args]{nostar-body}
\newcommand{\mycmd@star}[star-num-args]{star-body}
Many standard LaTeX environments or commands have a variant with the
same name but ending with a star character *, an asterisk.
Examples are the table and table* environments and the
\section and \section* commands.
When defining environments, following this pattern is straightforward
because \newenvironment and \renewenvironment allow the
environment name to contain a star. So you just have to write
\newenvironment{myenv} or
\newenvironment{myenv*} and continue the definition as
usual. For commands the situation is more complex as the star not being
a letter cannot be part of the command name. As in the synopsis above,
there will be a user-called command, given above as \mycmd, which
peeks ahead to see if it is followed by a star. For instance, LaTeX
does not really have a \section* command; instead, the
\section command peeks ahead. This command does not accept
arguments but instead expands to one of two commands that do accept
arguments. In the synopsis these two are \mycmd@nostar and
\mycmd@star. They could take the same number of arguments or a
different number, or no arguments at all. As always, in a LaTeX
document a command using an at-sign @ in its name must be
enclosed inside a \makeatletter ... \makeatother block
(see \makeatletter & \makeatother).
This example of \@ifstar defines the command \ciel and a
variant \ciel*. Both have one required argument. A call to
\ciel{blue} will return "not starry blue sky" while
\ciel*{night} will return "starry night sky".
\makeatletter
\newcommand*{\ciel@unstarred}[1]{not starry #1 sky}
\newcommand*{\ciel@starred}[1]{starry #1 sky}
\newcommand*{\ciel}{\@ifstar{\ciel@starred}{\ciel@unstarred}}
\makeatother
In the next example, the starred variant takes a different number of
arguments than the unstarred one. With this definition, Agent 007’s
``My name is \agentsecret*{Bond},
\agentsecret{James}{Bond}.'' is equivalent to entering the commands
``My name is \textsc{Bond}, \textit{James} textsc{Bond}.''
\newcommand*{\agentsecret@unstarred}[2]{\textit{#1} \textsc{#2}}
\newcommand*{\agentsecret@starred}[1]{\textsc{#1}}
\newcommand*{\agentsecret}{%
\@ifstar{\agentsecret@starred}{\agentsecret@unstarred}}
After a command name, a star is handled similarly to an optional
argument. (This differs from environment names in which the star is
part of the name itself and as such could be in any position.) Thus,
it is technically possible to put any number of spaces between the
command and the star. Thus \agentsecret*{Bond} and
\agentsecret *{Bond} are equivalent. However, the
standard practice is not to insert any such spaces.
There are two alternative ways to accomplish the work of
\@ifstar. (1) The suffix package allows the
construct \newcommand\mycommand{unstarred-variant}
followed by
\WithSuffix\newcommand\mycommand*{starred-variant}.
(2) LaTeX provides the xparse package, which allows
this code:
\NewDocumentCommand\foo{s}{\IfBooleanTF#1
{starred-variant}%
{unstarred-variant}%
}