\@ifstar (LaTeX2e unofficial reference manual (November 2018))

Next: \newcounter, Previous: \makeatletter & \makeatother, Up: Definitions [Contents][Index]

### 12.4 `\@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. For commands the situation is more complex. 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 at-sign `@` 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{night}` will return "starry night sky" while `\ciel*{blue}` will return "starry not blue sky".

    \newcommand*{\ciel@unstarred}[1]{starry #1 sky}
    \newcommand*{\ciel@starred}[1]{starry not #1 sky}
    \newcommand*{\ciel}{\@ifstar{\ciel@starred}{\ciel@unstarred}}

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}}

There are two sometimes more convenient ways to accomplish the work of `\@ifstar`. The `suffix` package allows the construct `\newcommand\mycommand{unstarred version}` followed by `\WithSuffix\newcommand\mycommand*{starred version}`. And LaTeX3 has the `xparse` package that allows this code.

    \NewDocumentCommand\foo{s}{\IfBooleanTF#1
      {starred version}%
      {unstarred version}%
      }

Unofficial LaTeX2e reference manual