%!TEX root = std.tex
% Definitions and redefinitions of special commands

%%--------------------------------------------------
%% Difference markups
\definecolor{addclr}{rgb}{0,.6,.6}
\definecolor{remclr}{rgb}{1,0,0}
\definecolor{noteclr}{rgb}{0,0,1}

\renewcommand{\added}[1]{\textcolor{addclr}{\uline{#1}}}
\newcommand{\removed}[1]{\textcolor{remclr}{\sout{#1}}}
\renewcommand{\changed}[2]{\removed{#1}\added{#2}}

\newcommand{\nbc}[1]{[#1]\ }
\newcommand{\addednb}[2]{\added{\nbc{#1}#2}}
\newcommand{\removednb}[2]{\removed{\nbc{#1}#2}}
\newcommand{\changednb}[3]{\removednb{#1}{#2}\added{#3}}
\newcommand{\remitem}[1]{\item\removed{#1}}

\newcommand{\ednote}[1]{\textcolor{noteclr}{[Editor's note: #1] }}
% \newcommand{\ednote}[1]{}

\newenvironment{addedblock}
{
\color{addclr}
}
{
\color{black}
}
\newenvironment{removedblock}
{
\color{remclr}
}
{
\color{black}
}

%%--------------------------------------------------
%% Grammar extraction.
\def\gramSec[#1]#2{}

\makeatletter
\newcommand{\FlushAndPrintGrammar}{%
\immediate\closeout\XTR@out%
\immediate\openout\XTR@out=std-gram-dummy.tmp%
\def\gramSec[##1]##2{\rSec1[##1]{##2}}%
\input{std-gram.ext}%
}
\makeatother

%%--------------------------------------------------
% Escaping for index entries. Replaces ! with "! throughout its argument.
\def\indexescape#1{\doindexescape#1\stopindexescape!\doneindexescape}
\def\doindexescape#1!{#1"!\doindexescape}
\def\stopindexescape#1\doneindexescape{}

%%--------------------------------------------------
%% Cross references.
\newcommand{\addxref}[1]{%
 \glossary[xrefindex]{\indexescape{#1}}{(\ref{\indexescape{#1}})}%
}

%%--------------------------------------------------
%% Sectioning macros.
% Each section has a depth, an automatically generated section
% number, a name, and a short tag.  The depth is an integer in
% the range [0,5].  (If it proves necessary, it wouldn't take much
% programming to raise the limit from 5 to something larger.)

% Set the xref label for a clause to be "Clause n", not just "n".
\makeatletter
\newcommand{\customlabel}[2]{%
\protected@write \@auxout {}{\string \newlabel {#1}{{#2}{\thepage}{#2}{#1}{}} }%
\hypertarget{#1}{}%
}
\makeatother
\newcommand{\clauselabel}[1]{\customlabel{#1}{Clause \thechapter}}
\newcommand{\annexlabel}[1]{\customlabel{#1}{Annex \thechapter}}

% The basic sectioning command.  Example:
%    \Sec1[intro.scope]{Scope}
% defines a first-level section whose name is "Scope" and whose short
% tag is intro.scope.  The square brackets are mandatory.
\def\Sec#1[#2]#3{%
\ifcase#1\let\s=\chapter\let\l=\clauselabel
      \or\let\s=\section\let\l=\label
      \or\let\s=\subsection\let\l=\label
      \or\let\s=\subsubsection\let\l=\label
      \or\let\s=\paragraph\let\l=\label
      \or\let\s=\subparagraph\let\l=\label
      \fi%
\s[#3]{#3\hfill[#2]}\l{#2}\addxref{#2}}

% A convenience feature (mostly for the convenience of the Project
% Editor, to make it easy to move around large blocks of text):
% the \rSec macro is just like the \Sec macro, except that depths
% relative to a global variable, SectionDepthBase.  So, for example,
% if SectionDepthBase is 1,
%   \rSec1[temp.arg.type]{Template type arguments}
% is equivalent to
%   \Sec2[temp.arg.type]{Template type arguments}
\newcounter{SectionDepthBase}
\newcounter{SectionDepth}

\def\rSec#1[#2]#3{%
\setcounter{SectionDepth}{#1}
\addtocounter{SectionDepth}{\value{SectionDepthBase}}
\Sec{\arabic{SectionDepth}}[#2]{#3}}

%%--------------------------------------------------
% Indexing

% locations
\newcommand{\indextext}[1]{\index[generalindex]{#1}}
\newcommand{\indexlibrary}[1]{\index[libraryindex]{#1}}
\newcommand{\indexhdr}[1]{\indextext{\idxhdr{#1}}\index[headerindex]{\idxhdr{#1}}}
\newcommand{\indexgram}[1]{\index[grammarindex]{#1}}

% Collation helper: When building an index key, replace all macro definitions
% in the key argument with a no-op for purposes of collation.
\newcommand{\nocode}[1]{#1}
\newcommand{\idxmname}[1]{\_\_#1\_\_}
\newcommand{\idxCpp}{C++}

% \indeximpldef synthesizes a collation key from the argument; that is, an
% invocation \indeximpldef{arg} emits an index entry `key@arg`, where `key`
% is derived from `arg` by replacing the folowing list of commands with their
% bare content. This allows, say, collating plain text and code.
\newcommand{\indeximpldef}[1]{%
\let\otextup\textup%
\let\textup\nocode%
\let\otcode\tcode%
\let\tcode\nocode%
\let\ogrammarterm\grammarterm%
\let\grammarterm\nocode%
\let\omname\mname%
\let\mname\idxmname%
\let\oCpp\Cpp%
\let\Cpp\idxCpp%
\let\oBreakableUnderscore\BreakableUnderscore%  See the "underscore" package.
\let\BreakableUnderscore\textunderscore%
\edef\x{#1}%
\let\tcode\otcode%
\let\grammarterm\gterm%
\let\mname\omname%
\let\Cpp\oCpp%
\let\BreakableUnderscore\oBreakableUnderscore%
\index[impldefindex]{\x@#1}%
\let\grammarterm\ogrammarterm%
\let\textup\otextup%
}

\newcommand{\indexdefn}[1]{\indextext{#1}}
\newcommand{\idxbfpage}[1]{\textbf{\hyperpage{#1}}}
\newcommand{\indexgrammar}[1]{\indextext{#1}\indexgram{#1|idxbfpage}}
% This command uses the "cooked" \indeximpldef command to emit index
% entries; thus they only work for simple index entries that do not contain
% special indexing instructions.
\newcommand{\impldef}[1]{\indeximpldef{#1}implementation-defined}
% \impldefplain passes the argument directly to the index, allowing you to
% use special indexing instructions (!, @, |).
\newcommand{\impldefplain}[1]{\index[impldefindex]{#1}implementation-defined}

% appearance
\newcommand{\idxcode}[1]{#1@\tcode{#1}}
\newcommand{\idxhdr}[1]{#1@\tcode{<#1>}}
\newcommand{\idxgram}[1]{#1@\gterm{#1}}
\newcommand{\idxxname}[1]{__#1@\xname{#1}}

% class member library index
\newcommand{\indexlibrarymember}[2]{\indexlibrary{\idxcode{#1}!\idxcode{#2}}\indexlibrary{\idxcode{#2}!\idxcode{#1}}}

%%--------------------------------------------------
% General code style
\newcommand{\CodeStyle}{\ttfamily}
\newcommand{\CodeStylex}[1]{\texttt{#1}}

% General grammar style
\newcommand{\GrammarStyle}{\itfamily}
\newcommand{\GrammarStylex}[1]{\textit{#1}}

% Code and definitions embedded in text.
\newcommand{\tcode}[1]{\CodeStylex{#1}}
\newcommand{\term}[1]{\textit{#1}}
\newcommand{\gterm}[1]{\GrammarStylex{#1}}
\newcommand{\fakegrammarterm}[1]{\gterm{#1}}
\newcommand{\grammarterm}[1]{\indexgram{\idxgram{#1}}\gterm{#1}}
\newcommand{\grammartermnc}[1]{\indexgram{\idxgram{#1}}\gterm{#1\nocorr}}
\newcommand{\placeholder}[1]{\textit{#1}}
\newcommand{\placeholdernc}[1]{\textit{#1\nocorr}}
\newcommand{\defnxname}[1]{\indextext{\idxxname{#1}}\xname{#1}}
\newcommand{\defnlibxname}[1]{\indexlibrary{\idxxname{#1}}\xname{#1}}

% Non-compound defined term.
\newcommand{\defn}[1]{\defnx{#1}{#1}}
% Defined term with different index entry.
\newcommand{\defnx}[2]{\indexdefn{#2}\textit{#1}}
% Compound defined term with 'see' for primary term.
% Usage: \defnadj{trivial}{class}
\newcommand{\defnadj}[2]{\indextext{#1 #2|see{#2, #1}}\indexdefn{#2!#1}\textit{#1 #2}}

%%--------------------------------------------------
%% allow line break if needed for justification
\newcommand{\brk}{\discretionary{}{}{}}

%%--------------------------------------------------
%% Macros for funky text
\newcommand{\Cpp}{\texorpdfstring{C\kern-0.05em\protect\raisebox{.35ex}{\textsmaller[2]{+\kern-0.05em+}}}{C++}}
\newcommand{\CppIII}{\Cpp{} 2003}
\newcommand{\CppXI}{\Cpp{} 2011}
\newcommand{\CppXIV}{\Cpp{} 2014}
\newcommand{\CppXVII}{\Cpp{} 2017}
\newcommand{\opt}[1]{#1\ensuremath{_\mathit{opt}}}
\newcommand{\dcr}{-{-}}
\newcommand{\bigoh}[1]{\ensuremath{\mathscr{O}(#1)}}

% Make all tildes a little larger to avoid visual similarity with hyphens.
\renewcommand{\~}{\textasciitilde}
\let\OldTextAsciiTilde\textasciitilde
\renewcommand{\textasciitilde}{\protect\raisebox{-0.17ex}{\larger\OldTextAsciiTilde}}
\newcommand{\caret}{\char`\^}

%%--------------------------------------------------
%% States and operators
\newcommand{\state}[2]{\tcode{#1}\ensuremath{_{#2}}}
\newcommand{\bitand}{\ensuremath{\mathbin{\mathsf{bitand}}}}
\newcommand{\bitor}{\ensuremath{\mathbin{\mathsf{bitor}}}}
\newcommand{\xor}{\ensuremath{\mathbin{\mathsf{xor}}}}
\newcommand{\rightshift}{\ensuremath{\mathbin{\mathsf{rshift}}}}
\newcommand{\leftshift}[1]{\ensuremath{\mathbin{\mathsf{lshift}_{#1}}}}

%% Notes and examples
\newcommand{\noteintro}[1]{[\textit{#1}:\space}
\newcommand{\noteoutro}[1]{\textit{\,---\,end #1}\kern.5pt]}
\newenvironment{note}[1][Note]{\noteintro{#1}}{\noteoutro{note}\space}
\newenvironment{example}[1][Example]{\noteintro{#1}}{\noteoutro{example}\space}

%% Library function descriptions
\newcommand{\Fundescx}[1]{\textit{#1}}
\newcommand{\Fundesc}[1]{\Fundescx{#1:}\space}
\newcommand{\required}{\Fundesc{Required behavior}}
\newcommand{\requires}{\Fundesc{Requires}}
\newcommand{\constraints}{\Fundesc{Constraints}}
\newcommand{\mandates}{\Fundesc{Mandates}}
\newcommand{\expects}{\Fundesc{Expects}}
\newcommand{\effects}{\Fundesc{Effects}}
\newcommand{\ensures}{\Fundesc{Ensures}}
\newcommand{\postconditions}{\ensures}
\newcommand{\returns}{\Fundesc{Returns}}
\newcommand{\throws}{\Fundesc{Throws}}
\newcommand{\default}{\Fundesc{Default behavior}}
\newcommand{\complexity}{\Fundesc{Complexity}}
\newcommand{\remarks}{\Fundesc{Remarks}}
\newcommand{\errors}{\Fundesc{Error conditions}}
\newcommand{\sync}{\Fundesc{Synchronization}}
\newcommand{\implimits}{\Fundesc{Implementation limits}}
\newcommand{\replaceable}{\Fundesc{Replaceable}}
\newcommand{\returntype}{\Fundesc{Return type}}
\newcommand{\cvalue}{\Fundesc{Value}}
\newcommand{\ctype}{\Fundesc{Type}}
\newcommand{\ctypes}{\Fundesc{Types}}
\newcommand{\dtype}{\Fundesc{Default type}}
\newcommand{\ctemplate}{\Fundesc{Class template}}
\newcommand{\templalias}{\Fundesc{Alias template}}

%% Cross reference
\newcommand{\xref}{\textsc{See also:}\space}
\newcommand{\xrefc}[1]{\xref{} ISO C #1}

%% Inline parenthesized reference
\newcommand{\iref}[1]{\nolinebreak[3] (\ref{#1})}

%% Inline non-parenthesized table reference (override memoir's \tref)
\renewcommand{\tref}[1]{\tablerefname \nolinebreak[3] \ref{tab:#1}}

%% NTBS, etc.
\newcommand{\NTS}[1]{\textsc{#1}}
\newcommand{\ntbs}{\NTS{ntbs}}
\newcommand{\ntmbs}{\NTS{ntmbs}}
% The following are currently unused:
% \newcommand{\ntwcs}{\NTS{ntwcs}}
% \newcommand{\ntcxvis}{\NTS{ntc16s}}
% \newcommand{\ntcxxxiis}{\NTS{ntc32s}}

%% Code annotations
\newcommand{\EXPO}[1]{\textit{#1}}
\newcommand{\expos}{\EXPO{exposition only}}
\newcommand{\impdef}{\EXPO{implementation-defined}}
\newcommand{\impdefnc}{\EXPO{implementation-defined\nocorr}}
\newcommand{\impdefx}[1]{\indeximpldef{#1}\EXPO{implementation-defined}}
\newcommand{\notdef}{\EXPO{not defined}}

\newcommand{\UNSP}[1]{\textit{\texttt{#1}}}
\newcommand{\UNSPnc}[1]{\textit{\texttt{#1}\nocorr}}
\newcommand{\unspec}{\UNSP{unspecified}}
\newcommand{\unspecnc}{\UNSPnc{unspecified}}
\newcommand{\unspecbool}{\UNSP{unspecified-bool-type}}
\newcommand{\seebelow}{\UNSP{see below}}
\newcommand{\seebelownc}{\UNSPnc{see below}}
\newcommand{\unspecuniqtype}{\UNSP{unspecified unique type}}
\newcommand{\unspecalloctype}{\UNSP{unspecified allocator type}}

%% Manual insertion of italic corrections, for aligning in the presence
%% of the above annotations.
\newlength{\itcorrwidth}
\newlength{\itletterwidth}
\newcommand{\itcorr}[1][]{%
 \settowidth{\itcorrwidth}{\textit{x\/}}%
 \settowidth{\itletterwidth}{\textit{x\nocorr}}%
 \addtolength{\itcorrwidth}{-1\itletterwidth}%
 \makebox[#1\itcorrwidth]{}%
}

%% Double underscore
\newcommand{\ungap}{\kern.5pt}
\newcommand{\unun}{\textunderscore\ungap\textunderscore}
\newcommand{\xname}[1]{\tcode{\unun\ungap#1}}
\newcommand{\mname}[1]{\tcode{\unun\ungap#1\ungap\unun}}

%% An elided code fragment, /* ... */, that is formatted as code.
%% (By default, listings typeset comments as body text.)
%% Produces 9 output characters.
\newcommand{\commentellip}{\tcode{/* ...\ */}}

%% Concepts
\newcommand{\oldconcept}[1]{\textit{Cpp17#1}}
\newcommand{\oldconceptdefn}[1]{\defn{Cpp17#1}}
\newcommand{\idxoldconcept}[1]{Cpp17#1@\textit{Cpp17#1}}
\newcommand{\libconcept}[1]{\tcode{#1}}

%% Ranges
\newcommand{\Range}[4]{\tcode{#1#3,\penalty2000{} #4#2}}
\newcommand{\crange}[2]{\Range{[}{]}{#1}{#2}}
\newcommand{\brange}[2]{\Range{(}{]}{#1}{#2}}
\newcommand{\orange}[2]{\Range{(}{)}{#1}{#2}}
\newcommand{\range}[2]{\Range{[}{)}{#1}{#2}}

%% Change descriptions
\newcommand{\diffdef}[1]{\hfill\break\textbf{#1:}\space}
\newcommand{\diffref}[1]{\pnum\textbf{Affected subclause:} \ref{#1}}
\newcommand{\diffrefs}[2]{\pnum\textbf{Affected subclauses:} \ref{#1}, \ref{#2}}
% \nodiffref swallows a following \change and removes the preceding line break.
\def\nodiffref\change{\pnum\textbf{Change:}\space}
\newcommand{\change}{\diffdef{Change}}
\newcommand{\rationale}{\diffdef{Rationale}}
\newcommand{\effect}{\diffdef{Effect on original feature}}
\newcommand{\difficulty}{\diffdef{Difficulty of converting}}
\newcommand{\howwide}{\diffdef{How widely used}}

%% Miscellaneous
\newcommand{\uniquens}{\placeholdernc{unique}}
\newcommand{\stage}[1]{\item[Stage #1:]}
\newcommand{\doccite}[1]{\textit{#1}}
\newcommand{\cvqual}[1]{\textit{#1}}
\newcommand{\cv}{\ifmmode\mathit{cv}\else\cvqual{cv}\fi}
\newcommand{\numconst}[1]{\textsl{#1}}
\newcommand{\logop}[1]{{\footnotesize #1}}

%%--------------------------------------------------
%% Environments for code listings.

% We use the 'listings' package, with some small customizations.  The
% most interesting customization: all TeX commands are available
% within comments.  Comments are set in italics, keywords and strings
% don't get special treatment.

\lstset{language=C++,
        basicstyle=\small\CodeStyle,
        keywordstyle=,
        stringstyle=,
        xleftmargin=1em,
        showstringspaces=false,
        commentstyle=\itshape\rmfamily,
        columns=fullflexible,
        keepspaces=true,
        texcl=true}

% Our usual abbreviation for 'listings'.  Comments are in
% italics.  Arbitrary TeX commands can be used if they're
% surrounded by @ signs.
\newcommand{\CodeBlockSetup}{%
\lstset{escapechar=@, aboveskip=\parskip, belowskip=0pt,
        midpenalty=500, endpenalty=-50,
        emptylinepenalty=-250, semicolonpenalty=0}%
\renewcommand{\tcode}[1]{\textup{\CodeStylex{##1}}}%
\renewcommand{\term}[1]{\textit{##1}}%
\renewcommand{\grammarterm}[1]{\gterm{##1}}%
}

\lstnewenvironment{codeblock}{\CodeBlockSetup}{}

% An environment for command / program output that is not C++ code.
\lstnewenvironment{outputblock}{\lstset{language=}}{}

% A code block in which single-quotes are digit separators
% rather than character literals.
\lstnewenvironment{codeblockdigitsep}{
 \CodeBlockSetup
 \lstset{deletestring=[b]{'}}
}{}

% Permit use of '@' inside codeblock blocks (don't ask)
\makeatletter
\newcommand{\atsign}{@}
\makeatother

%%--------------------------------------------------
%% Indented text
\newenvironment{indented}[1][]
{\begin{indenthelper}[#1]\item\relax}
{\end{indenthelper}}

%%--------------------------------------------------
%% Library item descriptions
\lstnewenvironment{itemdecl}
{
 \lstset{escapechar=@,
 xleftmargin=0em,
 midpenalty=500,
 semicolonpenalty=-50,
 endpenalty=3000,
 aboveskip=2ex,
 belowskip=0ex	% leave this alone: it keeps these things out of the
				% footnote area
 }
}
{
}

\newenvironment{itemdescr}
{
 \begin{indented}[beginpenalty=3000, endpenalty=-300]}
{
 \end{indented}
}


%%--------------------------------------------------
%% Bnf environments
\newlength{\BnfIndent}
\setlength{\BnfIndent}{\leftmargini}
\newlength{\BnfInc}
\setlength{\BnfInc}{\BnfIndent}
\newlength{\BnfRest}
\setlength{\BnfRest}{2\BnfIndent}
\newcommand{\BnfNontermshape}{\small\rmfamily\itshape}
\newcommand{\BnfTermshape}{\small\ttfamily\upshape}

\newenvironment{bnfbase}
 {
 \newcommand{\nontermdef}[1]{{\BnfNontermshape##1\itcorr}\indexgrammar{\idxgram{##1}}\textnormal{:}}
 \newcommand{\terminal}[1]{{\BnfTermshape ##1}}
 \newcommand{\descr}[1]{\textnormal{##1}}
 \newcommand{\bnfindent}{\hspace*{\bnfindentfirst}}
 \newcommand{\bnfindentfirst}{\BnfIndent}
 \newcommand{\bnfindentinc}{\BnfInc}
 \newcommand{\bnfindentrest}{\BnfRest}
 \newcommand{\br}{\hfill\\*}
 \widowpenalties 1 10000
 \frenchspacing
 }
 {
 \nonfrenchspacing
 }

\newenvironment{simplebnf}
{
 \begin{bnfbase}
 \BnfNontermshape
 \begin{indented}[before*=\setlength{\rightmargin}{-\leftmargin}]
}
{
 \end{indented}
 \end{bnfbase}
}

\newenvironment{bnf}
{
 \begin{bnfbase}
 \begin{bnflist}
 \BnfNontermshape
 \item\relax
}
{
 \end{bnflist}
 \end{bnfbase}
}

% non-copied versions of bnf environments
\let\ncsimplebnf\simplebnf
\let\endncsimplebnf\endsimplebnf
\let\ncbnf\bnf
\let\endncbnf\endbnf

%%--------------------------------------------------
%% Drawing environment
%
% usage: \begin{drawing}{UNITLENGTH}{WIDTH}{HEIGHT}{CAPTION}
\newenvironment{drawing}[4]
{
\newcommand{\mycaption}{#4}
\begin{figure}[h]
\setlength{\unitlength}{#1}
\begin{center}
\begin{picture}(#2,#3)\thicklines
}
{
\end{picture}
\end{center}
\caption{\mycaption}
\end{figure}
}

%%--------------------------------------------------
%% Environment for imported graphics
% usage: \begin{importgraphic}{CAPTION}{TAG}{FILE}

\newenvironment{importgraphic}[3]
{%
\newcommand{\cptn}{#1}
\newcommand{\lbl}{#2}
\begin{figure}[htp]\centering%
\includegraphics[scale=.35]{#3}
}
{
\caption{\cptn}\label{\lbl}%
\end{figure}}

%% enumeration display overrides
% enumerate with lowercase letters
\newenvironment{enumeratea}
{
 \renewcommand{\labelenumi}{\alph{enumi})}
 \begin{enumerate}
}
{
 \end{enumerate}
}

%%--------------------------------------------------
%% Definitions section for "Terms and definitions"
\newcounter{termnote}
\newcommand{\nocontentsline}[3]{}
\newcommand{\definition}[2]{%
\addxref{#2}%
\setcounter{termnote}{0}%
\let\oldcontentsline\addcontentsline%
\let\addcontentsline\nocontentsline%
\ifcase\value{SectionDepth}
         \let\s=\section
      \or\let\s=\subsection
      \or\let\s=\subsubsection
      \or\let\s=\paragraph
      \or\let\s=\subparagraph
      \fi%
\s[#1]{\hfill[#2]}\vspace{-.3\onelineskip}\label{#2} \textbf{#1}\\*%
\let\addcontentsline\oldcontentsline%
}
\newcommand{\defncontext}[1]{\textlangle#1\textrangle}
\newenvironment{defnote}{\addtocounter{termnote}{1}\noteintro{Note \thetermnote{} to entry}}{\noteoutro{note}\space}

