summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/xstring/xstring_doc_en.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/xstring/xstring_doc_en.tex')
-rw-r--r--Master/texmf-dist/doc/latex/xstring/xstring_doc_en.tex224
1 files changed, 165 insertions, 59 deletions
diff --git a/Master/texmf-dist/doc/latex/xstring/xstring_doc_en.tex b/Master/texmf-dist/doc/latex/xstring/xstring_doc_en.tex
index 3985badad65..88e65f4d514 100644
--- a/Master/texmf-dist/doc/latex/xstring/xstring_doc_en.tex
+++ b/Master/texmf-dist/doc/latex/xstring/xstring_doc_en.tex
@@ -38,6 +38,7 @@
\newcommand\arguC[1]{\texttt{[}\argu{#1}\texttt{]}}
\newcommand\arguCC[2]{\texttt{[}\argu{#1}{,}\argu{#2}\texttt{]}}
\newcommand\texte[1]{\texttt{text}${}_{#1}$}
+\newcommand\etoile{$\langle$\texttt{[*]}$\rangle$}
\newcommand\voirdeftexte{~(see \ref{deftexte})}
\newenvironment{Conditions}[1][1cm]%
{\begin{list}%
@@ -96,6 +97,7 @@
\item length of a string;
\item position of the $n$\th{} occurrence of a substring;
\item how many times a string contains a substring?
+ \item comparison of 2 strings: position of the first difference.
\end{itemize}
\end{itemize}
\setlength{\parindent}{0pt}
@@ -114,7 +116,9 @@ This manual is a translation of the french manual. I apologize for my poor engli
\subsection{Description}
This extension\footnote{This extension does not require \LaTeX{} and can be compiled with Plain $\varepsilon$-\TeX{}.} provides macros and tests operating on strings, as other programmation languages have. They provides the usual strings operations, such as: test if a string contains another, begins or ends with another, extractions of strings, calculation of the position of a substring, of the number of occurrences, etc.\medskip
-Certainly, other packages exist (for example \href{http://www.ctan.org/tex-archive/macros/latex/contrib/substr/}{\nolinkurl{substr}} and \href{http://www.ctan.org/tex-archive/macros/latex/contrib/stringstrings/}{\nolinkurl{stringstrings}}), but as well as differences on features, they do not take into account occurrences so I found them too limited and difficult to use for programming.
+Certainly, other packages exist (for example \href{http://www.ctan.org/tex-archive/macros/latex/contrib/substr/}{\nolinkurl{substr}} and \href{http://www.ctan.org/tex-archive/macros/latex/contrib/stringstrings/}{\nolinkurl{stringstrings}}), but as well as differences on features, they do not take into account occurrences so I found them too limited and difficult to use for programming.\medskip
+
+There are 2 forms of each command of this package : the regular one and the starred one. The difference is that the regular \emph{do take care of catcodes} of the characters in the string, while the starred ones, \emph{less strict}, don't. For most users, both should behave the same way (for advanced user, read more at page~\pageref{catcodesarguments} and page~\pageref{macrosetoilees}).
\subsection{Motivation}
I decided to write this package of macros because I have never really found tools in \LaTeX{} suiting my needs for strings. So, over the last few months,I wrote a few macros that I occasionally or regularly used. Their numbers have increased and become a little too dispersed in directories in my computer, so I have grouped them together in this package.
@@ -153,7 +157,7 @@ The structure on the left allow to forget the order of expansion and avoid writi
However, at any time, you can find the usual order of expansion with the macro \verb|\normalexpandarg|, and use again \verb|\fullexpandarg| if you want a full expansion of the arguments.
\subsubsection{Textual arguments}
-The macros operating on strings require one or several arguments containing --~or whose expansion contains~-- \texte{10,11,12}\voirdeftexte{}, using the usual syntax \verb|{|\texte{10,11,12}\verb|}|, and for optionnal arguments \verb|[|\texte{10,11,12}\verb|]|.\medskip
+The macros operating on strings require one or several arguments containing --~or whose expansion contains~-- \texte{10,11,12}\voirdeftexte{}, using the usual syntax \verb|{|\texte{10,11,12}\verb|}|, and for optional arguments \verb|[|\texte{10,11,12}\verb|]|.\medskip
The following rules shoud be observed for the expansion of textual arguments:
@@ -172,7 +176,7 @@ The macros of this package are not purely expandable, i.e. they cannot be put in
\qquad or this nested structure\par
\hspace{0.2\linewidth}\verb|\commandA{\commandB{\commandC{argument}}}|\smallskip
-For this reason, all the macros returning a result (i.e. all excepted the tests) have an optionnal argument in last position. The syntax is \arguC{name}, where \argu{name} is the name of the control sequence that will receive the result of the macro: the assignment is made with an \verb|\edef| which make the result of the macro \argu{name} purely expandable. Of course, if an optionnal argument is present, the macro does not display anything.\medskip
+For this reason, all the macros returning a result (i.e. all excepted the tests and \verb|\StrSplit|) have an optional argument in last position. The syntax is \arguC{name}, where \argu{name} is the name of the control sequence that will receive the result of the macro: the assignment is made with an \verb|\edef| which make the result of the macro \argu{name} purely expandable. Of course, if an optional argument is present, the macro does not display anything.\medskip
Thus, this structure not allowed, already seen above:\par
\hspace{0.2\linewidth}\verb|\edef\Result{\command{arguments}}|\par
@@ -186,6 +190,15 @@ And this nested one:\par
\hspace{0.2\linewidth}\verb|\commandB{\MyString}[\MyString]|\par
\hspace{0.2\linewidth}\verb|\commandA{\MyString}|
+\subsubsection{Catcode of arguments}\label{catcodesarguments}
+Macros of this package take the catcodes of characters into account. To avoid unexpected behaviour (particulary with tests), you should keep in mind that characters \emph{and their catcodes} are examined.\medskip
+
+For instance, these two arguments:\par\medskip
+\hfil\verb|{\string a\string b}|\qquad and\qquad\verb|{ab}|\hfil{}\par\smallskip
+do \emph{not} expand into equal strings for xstring! Because of the command \verb|\string|, the first expands into ''\verb|ab|`` with catcodes 12 while the second have characters with their natural catcodes 11. Catcodes do not match! It is necessary to be aware of this, particulary with command like \verb|\string| which expansion is a string with catcodes 12 and 10 : \verb|\detokenize|, \verb|\meaning|, \verb|\jobname|, \verb|\fontname|, \verb|\romannumeral|, etc.\medskip
+
+Starred macros do not take catcodes into account. They simply convert their textual arguments into arguments with catcodes 12 and 10, and call the non-starred macros with these modified arguments. For more information about this, read page~\pageref{macrosetoilees}.
+
\section{The macros}
\label{listemacros}
\subsection{Presentation of macros}
@@ -200,7 +213,7 @@ In the following chapters, all the macros will be presented this plan:\smallskip
\subsection{The tests}
\subsubsection{IfSubStr}
-\verb|\IfSubStr|\arguC{number}\ARGU{string}\ARGU{stringA}\ARGU{true}\ARGU{false}
+\verb|\IfSubStr|\etoile\arguC{number}\ARGU{string}\ARGU{stringA}\ARGU{true}\ARGU{false}
\smallskip
The value of the optional argument \argu{number} is 1 by default.\par\smallskip
@@ -221,7 +234,7 @@ Tests if \argu{string} contains at least \argu{number} times \argu{stringA} and
\exemple|\IfSubStr[4]{1a2a3a}{a}{true}{false}|
\subsubsection{IfSubStrBefore}
-\verb|\IfSubStrBefore|\arguCC{number1}{number2}\ARGU{string}\ARGU{stringA}\ARGU{stringB}\ARGU{true}\ARGU{false}
+\verb|\IfSubStrBefore|\etoile\arguCC{number1}{number2}\ARGU{string}\ARGU{stringA}\ARGU{stringB}\ARGU{true}\ARGU{false}
\smallskip
The values of the optional arguments \argu{number1} and \argu{number2} are 1 by default.\par\smallskip
@@ -246,7 +259,7 @@ In \argu{string}, tests if the \argu{number1}\th{} occurrence of \argu{stringA}
\subsubsection{IfSubStrBehind}
-\verb|\IfSubStrBehind|\arguCC{number1}{number2}\ARGU{string}\ARGU{stringA}\ARGU{stringB}\ARGU{true}\ARGU{false}
+\verb|\IfSubStrBehind|\etoile\arguCC{number1}{number2}\ARGU{string}\ARGU{stringA}\ARGU{stringB}\ARGU{true}\ARGU{false}
\smallskip
The values of the optional arguments \argu{number1} and \argu{number2} are 1 by default.\par\smallskip
@@ -271,7 +284,7 @@ In \argu{string}, tests if the \argu{number1}\th{} occurrence of \argu{stringA}
\subsubsection{IfBeginWith}
-\verb|\IfBeginWith|\ARGU{string}\ARGU{stringA}\ARGU{true}\ARGU{false}
+\verb|\IfBeginWith|\etoile\ARGU{string}\ARGU{stringA}\ARGU{true}\ARGU{false}
\smallskip
Tests if \argu{string} begins with \argu{stringA}, and runs \argu{true} if so, and \argu{false} otherwise.\medskip
@@ -287,7 +300,7 @@ Tests if \argu{string} begins with \argu{stringA}, and runs \argu{true} if so, a
\subsubsection{IfEndWith}
-\verb|\IfEndWith|\ARGU{string}\ARGU{stringA}\ARGU{Behind}\ARGU{false}
+\verb|\IfEndWith|\etoile\ARGU{string}\ARGU{stringA}\ARGU{Behind}\ARGU{false}
\smallskip
Tests if \argu{string} ends with \argu{stringA}, and runs \argu{true} if so, and \argu{false} otherwise.\medskip
@@ -303,7 +316,7 @@ Tests if \argu{string} ends with \argu{stringA}, and runs \argu{true} if so, and
\subsubsection{IfInteger}
-\verb|\IfInteger|\ARGU{number}\ARGU{true}\ARGU{false}
+\verb|\IfInteger|\etoile\ARGU{number}\ARGU{true}\ARGU{false}
\smallskip
Tests if \argu{number} is an integer, and runs \argu{true} if so, and \argu{false} otherwise.\smallskip
@@ -322,7 +335,7 @@ If test is false because unexpected characters, the control sequence \verb|\@xs@
\subsubsection{IfDecimal}\label{ifdecimal}
-\verb|\IfInteger|\ARGU{number}\ARGU{true}\ARGU{false}
+\verb|\IfDecimal|\etoile\ARGU{number}\ARGU{true}\ARGU{false}
\smallskip
Tests if \argu{number} is a decimal, and runs \argu{true} if so, and \argu{false} otherwise.\smallskip
@@ -354,7 +367,7 @@ If test is false because unexpected characters, the control sequence \verb|\@xs@
\subsubsection{IfStrEq}
-\verb|\IfStrEq|\ARGU{stringA}\ARGU{stringB}\ARGU{true}\ARGU{false}
+\verb|\IfStrEq|\etoile\ARGU{stringA}\ARGU{stringB}\ARGU{true}\ARGU{false}
\smallskip
Tests if the strings \argu{stringA} and \argu{stringB} are equal, i.e. if they contain successively the same characters in the same order. Runs \argu{true} if so, and \argu{false} otherwise.\smallskip
@@ -370,14 +383,14 @@ Tests if the strings \argu{stringA} and \argu{stringB} are equal, i.e. if they c
\subsubsection{IfEq}
-\verb|\IfStrEq|\ARGU{stringA}\ARGU{stringB}\ARGU{true}\ARGU{false}
+\verb|\IfEq|\etoile\ARGU{stringA}\ARGU{stringB}\ARGU{true}\ARGU{false}
\smallskip
Tests if the strings \argu{stringA} and \argu{stringB} are equal, \emph{except} if both \argu{stringA} and \argu{stringB} contain numbers in which case the macro tests if these numbers are equal. Runs \argu{true} if so, and \argu{false} otherwise.\smallskip
\begin{Conditions}
\item The definition of \emph{number} is given with the macro \verb|IfDecimal| (see page~\pageref{ifdecimal}), and thus :
- \item \guill{+} signs are optionnal;
+ \item \guill{+} signs are optional;
\item Decimal separator can be a dot or a comma;
\item It is possible to evaluate an algebric expression with the $\varepsilon$-\TeX{} primitive \verb|\numexpr|, keeping in mind that it operate on integers only, and that results of divisions are \emph{rounded} and not truncated! It is wiser to avoid with no integer calculation.
\end{Conditions}
@@ -396,10 +409,50 @@ Tests if the strings \argu{stringA} and \argu{stringB} are equal, \emph{except}
\exemple|\IfEq{0}{-0.0}{true}{false}|
\exemple|\IfEq{}{}{true}{false}|
+\subsubsection{IfStrEqCase}
+
+\begin{minipage}{\textwidth}
+ \verb|\IfStrEqCase|\etoile\ARGU{string}\verb|{%|\par
+ \qquad\qquad\ARGU{string1}\ARGU{code1}\verb|%|\par
+ \qquad\qquad\ARGU{string2}\ARGU{code2}\verb|%|\par
+ \qquad\qquad\verb|etc...|\par
+ \qquad\qquad\ARGU{stringN}\ARGU{codeN}\verb|}|\arguC{other cases code}
+\end{minipage}
+\smallskip
+
+Tests successively if \argu{string} is equal to \argu{string1}, \argu{string2}, etc. Comparison is made with \verb|\IfStrEq| (see above). If the test $i$ is positive (the \argu{string} matches \argu{string\;$i$}), the macro runs \argu{code\;$i$} and ends. If all tests fail, the macro runs the optional \argu{other cases code}, if present.\smallskip
+
+\exemple|\IfStrEqCase{b}{{a}{AA}{b}{BB}{c}{CC}}|
+\exemple*|\IfStrEqCase{abc}{{a}{AA}{b}{BB}{c}{CC}}|
+\exemple|\IfStrEqCase{c}{{a}{AA}{b}{BB}{c}{CC}}[other]|
+\exemple|\IfStrEqCase{d}{{a}{AA}{b}{BB}{c}{CC}}[other]|
+\exemple|\IfStrEqCase{+3}{{1}{one}{2}{two}{3}{three}}[other]|
+\exemple|\IfStrEqCase{0.5}{{0}{zero}{.5}{half}{1}{one}}[other]|
+
+\subsubsection{IfEqCase}
+
+\begin{minipage}{\textwidth}
+ \verb|\IfEqCase|\etoile\ARGU{string}\verb|{%|\par
+ \qquad\qquad\ARGU{string1}\ARGU{code1}\verb|%|\par
+ \qquad\qquad\ARGU{string2}\ARGU{code2}\verb|%|\par
+ \qquad\qquad\verb|etc...|\par
+ \qquad\qquad\ARGU{stringN}\ARGU{codeN}\verb|}|\arguC{other cases code}
+\end{minipage}
+\smallskip
+
+Tests successively if \argu{string} is equal to \argu{string1}, \argu{string2}, etc. Comparison is made with \verb|\IEq| (see above). If the test $i$ is positive (the \argu{string} matches \argu{string\;$i$}), the macro runs \argu{code\;$i$} and ends. If all tests fail, the macro runs the optional \argu{other cases code}, if present.\smallskip
+
+\exemple|\IfEqCase{b}{{a}{AA}{b}{BB}{c}{CC}}|
+\exemple*|\IfEqCase{abc}{{a}{AA}{b}{BB}{c}{CC}}|
+\exemple|\IfEqCase{c}{{a}{AA}{b}{BB}{c}{CC}}[other]|
+\exemple|\IfEqCase{d}{{a}{AA}{b}{BB}{c}{CC}}[other]|
+\exemple|\IfEqCase{+3}{{1}{one}{2}{two}{3}{three}}[other]|
+\exemple|\IfEqCase{0.5}{{0}{zero}{.5}{half}{1}{one}}[other]|
+
\subsection{Extraction of substrings}
\subsubsection{StrBefore}
-\verb|\StrBefore|\arguC{number}\ARGU{string}\ARGU{stringA}\arguC{name}
+\verb|\StrBefore|\etoile\arguC{number}\ARGU{string}\ARGU{stringA}\arguC{name}
\smallskip
The value of the optional argument \argu{number} is 1 by default.\par\smallskip
@@ -423,7 +476,7 @@ In \argu{string}, returns what is leftwards the \argu{number}\th{} occurrence of
\subsubsection{StrBehind}
-\verb|\StrBehind|\arguC{number}\ARGU{string}\ARGU{stringA}\arguC{name}
+\verb|\StrBehind|\etoile\arguC{number}\ARGU{string}\ARGU{stringA}\arguC{name}
\smallskip
The value of the optional argument \argu{number} is 1 by default.\par\smallskip
@@ -449,7 +502,7 @@ In \argu{string}, returns what is rightwards the \argu{number}\th{} occurrence o
\subsubsection{StrBetween}
-\verb|\StrBetween|\arguCC{number1}{number2}\ARGU{string}\ARGU{stringA}\ARGU{stringB}\arguC{name}
+\verb|\StrBetween|\etoile\arguCC{number1}{number2}\ARGU{string}\ARGU{stringA}\ARGU{stringB}\arguC{name}
\smallskip
The values of the optional arguments \argu{number1} and \argu{number2} are 1 by default.\par\smallskip
@@ -475,7 +528,7 @@ In \argu{string}, returns the substring between\footnote{In a strict sense, i.e.
\subsubsection{StrSubstitute}
-\verb|\StrSubstitute|\arguC{number}\ARGU{string}\ARGU{stringA}\ARGU{stringB}\arguC{name}
+\verb|\StrSubstitute|\etoile\arguC{number}\ARGU{string}\ARGU{stringA}\ARGU{stringB}\arguC{name}
\smallskip
The value of the optional argument \argu{number} is 1 by default.\par\smallskip
@@ -503,7 +556,7 @@ In \argu{string}, substitute the \argu{number} first occurrences of \argu{string
\subsubsection{StrDel}
-\verb|\StrDel|\arguC{number}\ARGU{string}\ARGU{stringA}\arguC{name}
+\verb|\StrDel|\etoile\arguC{number}\ARGU{string}\ARGU{stringA}\arguC{name}
\smallskip
The value of the optional argument \argu{number} is 1 by default.\par\smallskip
@@ -523,12 +576,34 @@ Delete the \argu{number} first occurrences of \argu{stringA} in \argu{string}, e
\exemple|\StrDel[9]{abracadabra}{a}|
\exemple|\StrDel{a bc def }{ }|
+\subsubsection{StrSplit}
+\verb|\StrSplit|\etoile\ARGU{string}\ARGU{number}\ARGU{csA}\ARGU{csB}
+\smallskip
+
+The \argu{string}, is splitted after the character at position \argu{number}. The left part is assigned to the control sequence \argu{csA} and the right part is assigned to \argu{csB}.\par
+This macro returns two strings, so it does \emph{not} display anything. Consequently, it does not provide the optional argument in last position.\medskip
+
+\begin{Conditions}
+ \item If \argu{number}${}\leqslant0$, \argu{csA} is empty and \argu{csB} is equal to \argu{string};
+ \item If \argu{number}${}\geqslant$\argu{lengthString}, \argu{csA} is equal to \argu{string} and \argu{csB} is empty;
+ \item If \argu{string} is empty, \argu{csA} and \argu{csB} are empty, whatever be the integer \argu{number}.
+\end{Conditions}
+
+\setverbdelim{=}
+\exemple=\StrSplit{abcdef}{4}{\aa}{\bb}results: |\aa| and |\bb|=
+\exemple=\StrSplit{a b c }{2}{\aa}{\bb}results: |\aa| and |\bb|=
+\exemple=\StrSplit{abcdef}{1}{\aa}{\bb}results: |\aa| and |\bb|=
+\exemple=\StrSplit{abcdef}{5}{\aa}{\bb}results: |\aa| and |\bb|=
+\exemple=\StrSplit{abcdef}{9}{\aa}{\bb}results: |\aa| and |\bb|=
+\exemple=\StrSplit{abcdef}{-3}{\aa}{\bb}results: |\aa| and |\bb|=
+\setverbdelim{|}
+
\subsubsection{StrGobbleLeft}
-\verb|\StrGobbleLeft|\ARGU{string}\ARGU{number}\arguC{name}
+\verb|\StrGobbleLeft|\etoile\ARGU{string}\ARGU{number}\arguC{name}
\smallskip
-In \argu{string}, delete the \argu{number} fisrt characters on the left.\medskip
+In \argu{string}, delete the \argu{number} first characters on the left.\medskip
\begin{Conditions}
\item If \argu{string} is empty, an empty string is returned;
@@ -544,10 +619,10 @@ In \argu{string}, delete the \argu{number} fisrt characters on the left.\medskip
\subsubsection{StrLeft}
-\verb|\StrLeft|\ARGU{string}\ARGU{number}\arguC{name}
+\verb|\StrLeft|\etoile\ARGU{string}\ARGU{number}\arguC{name}
\smallskip
-In \argu{string}, returns the \argu{number} fisrt characters on the left.\medskip
+In \argu{string}, returns the \argu{number} first characters on the left.\medskip
\begin{Conditions}
\item If \argu{string} is empty, an empty string is returned;
@@ -563,7 +638,7 @@ In \argu{string}, returns the \argu{number} fisrt characters on the left.\medski
\subsubsection{StrGobbleRight}
-\verb|\StrGobbleRight|\ARGU{string}\ARGU{number}\arguC{name}
+\verb|\StrGobbleRight|\etoile\ARGU{string}\ARGU{number}\arguC{name}
\smallskip
In \argu{string}, delete the \argu{number} last characters on the right.\medskip
@@ -576,7 +651,7 @@ In \argu{string}, delete the \argu{number} last characters on the right.\medskip
\subsubsection{StrRight}
-\verb|\StrRight|\ARGU{string}\ARGU{number}\arguC{name}
+\verb|\StrRight|\etoile\ARGU{string}\ARGU{number}\arguC{name}
\smallskip
In \argu{string}, returns the \argu{number} last characters on the right.\medskip
@@ -589,7 +664,7 @@ In \argu{string}, returns the \argu{number} last characters on the right.\medski
\subsubsection{StrChar}
-\verb|\StrChar|\ARGU{string}\ARGU{number}\arguC{name}
+\verb|\StrChar|\etoile\ARGU{string}\ARGU{number}\arguC{name}
\smallskip
Returns the character at the position \argu{number} in \argu{string}.\medskip
@@ -606,7 +681,7 @@ Returns the character at the position \argu{number} in \argu{string}.\medskip
\subsubsection{StrMid}
-\verb|\StrMid|\ARGU{string}\ARGU{numberA}\ARGU{numberB}\arguC{name}
+\verb|\StrMid|\etoile\ARGU{string}\ARGU{numberA}\ARGU{numberB}\arguC{name}
\smallskip
In \argu{string}, returns the substring between\footnote{In the broad sense, i.e. that the strings characters of the \guill{border} are returned.} the positions \argu{numberA} and \argu{numberB}.\medskip
@@ -630,7 +705,7 @@ In \argu{string}, returns the substring between\footnote{In the broad sense, i.e
\subsection{Number results}
\subsubsection{StrLen}
-\verb|\StrLen|\ARGU{string}\arguC{name}
+\verb|\StrLen|\etoile\ARGU{string}\arguC{name}
\smallskip
Return the length of \argu{string}.
@@ -641,7 +716,7 @@ Return the length of \argu{string}.
\subsubsection{StrCount}
-\verb|\StrCount|\ARGU{string}\ARGU{stringA}\arguC{name}
+\verb|\StrCount|\etoile\ARGU{string}\ARGU{stringA}\arguC{name}
\smallskip
Counts how many times \argu{stringA} is contained in \argu{string}.\par\medskip
@@ -657,7 +732,7 @@ Counts how many times \argu{stringA} is contained in \argu{string}.\par\medskip
\subsubsection{StrPosition}
-\verb|\StrPosition|\arguC{number}\ARGU{string}\ARGU{stringA}\arguC{name}
+\verb|\StrPosition|\etoile\arguC{number}\ARGU{string}\ARGU{stringA}\arguC{name}
\smallskip
The value of the optional argument \argu{number} is 1 by default.\par\smallskip
@@ -678,6 +753,44 @@ In \argu{string}, returns the position of the \argu{number}\th{} occurrence of \
\exemple|\StrPosition{a bc def }{d}|
\exemple|\StrPosition[3]{aaaaaa}{aa}|
+\subsubsection{StrCompare}
+\verb|\StrCompare|\etoile\ARGU{stringA}\ARGU{stringB}\arguC{name}
+\smallskip
+
+This macro has 2 tolerances: the ''normal`` tolerance, used bu default, and the ''strict`` tolerance.\medskip
+
+\begin{itemize}
+ \item The normal tolerance, activated with \verb|\comparenormal|.\par
+ The macro compares characters from left to right in \argu{stringA} and \argu{stringB} until a difference appears or the end of the shortest string is reached. The position of the first difference is returned and if no difference is found, the macro return 0.
+ \item The strict tolerance, activated with \verb|\comparestrict|.\par
+ The macro compares the 2 strings. If they are equal, it returns 0. If not, the position of the first difference is returned.
+\end{itemize}
+\smallskip
+
+Examples with the normal tolerance:\par\comparenormal
+\exemple|\StrCompare{abcd}{abcd}|
+\exemple|\StrCompare{abcd}{abc}|
+\exemple|\StrCompare{abc}{abcd}|
+\exemple|\StrCompare{éùçà}{éùçà}|
+\exemple|\StrCompare{a b c}{abc}|
+\exemple|\StrCompare{aaa}{baaa}|
+\exemple|\StrCompare{abc}{xyz}|
+\exemple|\StrCompare{123456}{123457}|
+\exemple|\StrCompare{abc}{}|
+\medskip
+
+Examples with the strict tolerance:\par\comparestrict
+\exemple|\StrCompare{abcd}{abcd}|
+\exemple|\StrCompare{abcd}{abc}|
+\exemple|\StrCompare{abc}{abcd}|
+\exemple|\StrCompare{éùçà}{éùçà}|
+\exemple|\StrCompare{a b c}{abc}|
+\exemple|\StrCompare{aaa}{baaa}|
+\exemple|\StrCompare{abc}{xyz}|
+\exemple|\StrCompare{123456}{123457}|
+\exemple|\StrCompare{abc}{}|
+\comparenormal
+
\section{Using the macros for programming purposes}
\label{programmation}
\subsection{Verbatimize to a control sequence}
@@ -786,7 +899,7 @@ Indeed, with \verb|\scancs{\resultat}{\test}|, \verb|\result| contains \texte{10
With \verb|\edef\resultat{\test}|, \verb|\resultat| contains \texte{10,11,12}, i.e. characters whose catcodes are 11 (the letters), 12 (the figure 1) and 10 (the spaces). It expands to:\par
\hfill\verb|a|${}_{11}$\ \verb*| |${}_{10}$\ \verb|b|${}_{11}$\ \verb|1|${}_{12}$\ \verb*| |${}_{10}$\ \verb|d|${}_{11}$\hfill{}
-\subsubsection{Several expansions}
+\subsubsection{Depth of expansion}
If necessary, the number of expansions can be controled with the optional argument.
In the following example, when \verb|\scancs| is called the first time, \verb|\c| is expanded 3 times and gives "\verb|1|${}_{12}$\ \verb*| |${}_{10}$\ \verb|z|${}_{11}$\ \verb*| |${}_{10}$\ \verb|3|${}_{12}$" which is converted into "\verb|1|${}_{12}$\ \verb*| |${}_{10}$\ \verb|z|${}_{12}$\ \verb*| |${}_{10}$\ \verb|3|${}_{12}$".\smallskip
@@ -1007,51 +1120,44 @@ In the following teaching example\footnote{It is possible to make much more simp
\bracearg{\a}
\end{minipage}
-\subsection{Starred macros}
-As \verb|\scancs| returns \texte{10,12}\voirdeftexte, some unexpected results occur with the macros seen at chapter~\ref{listemacros} because they care the catcodes of the characters of their arguments.\medskip
+\subsection{Starred macros}\label{macrosetoilees}
+Commands manipulating strings take catcodes of characters into account. To prevent any differences between catcode and then avoid unexpected results, all these macros have starred version. Starred macros convert their textual arguments into arguments with catcode 12 and 10 and call the non-starred macros with these modified arguments.\medskip
-This is an example of such malfunctioning:\par\medskip
+Here is an example:\par\smallskip
\begin{minipage}[r]{0.6\linewidth}
\hfill
\begin{boxedverbatim}
- \verbtocs{\mytext}|a b c|
- \IfSubStr{\mytext}{b}{true}{false}
- \par
- \edef\onecs{x y z}
- \scancs[1]\mycs\onecs
- \IfSubStr{\mycs}{y}{true}{false}
+ \IfStrEq{\string a\string b}{ab}{true}{false}\par
+ \IfStrEq*{\string a\string b}{ab}{true}{false}
\end{boxedverbatim}
\hspace{0.3cm}
\end{minipage}%
\begin{minipage}[r]{0.3\linewidth}
- \verbtocs{\mytext}|a b c|
- \IfSubStr{\mytext}{b}{true}{false}
- \par
- \edef\onecs{x y z}
- \scancs[1]\mycs\onecs
- \IfSubStr{\mycs}{y}{true}{false}
-\end{minipage}
-\medskip
-
-The first test is "true" since catcodes of non special characters are left unchanged by \verb|\verbtocs|: indeed, \verb|\mytext| contains "\verb|a|${}_{11}$\ \verb*| |${}_{10}$\ \verb|b|${}_{11}$\ \verb*| |${}_{10}$\ \verb|c|${}_{11}$" which does contain the second argument "\verb|b|${}_{11}$".\medskip
+ \IfStrEq{\string a\string b}{ab}{true}{false}\par
+ \IfStrEq*{\string a\string b}{ab}{true}{false}
+\end{minipage}\smallskip
-With the second test, since \verb|\scancs| returns \texte{10,12}, it is false. \verb|\mycs| contains "\verb|x|${}_{12}$\ \verb*| |${}_{10}$\ \verb|y|${}_{12}$\ \verb*| |${}_{10}$\ \verb|z|${}_{12}$" which does not contains the second argument ""\verb|y|${}_{11}$".\bigskip
+In this example, the first argument expands into \verb|{ab}| where, because of \verb|\string|, both characters have a catcode 12. The second argument is \verb|{ab}| where characters have their natural catcode 11. The strings are \emph{not equal} because of unmatching catcodes. Therefore, the test is negative. It is positive only with the starred macro.\medskip
-To avoid this annoyance due unmatching catcodes, it is possible to make macros of chapter~\ref{listemacros} compatible with \verb|\scancs|: they all have a starred version that converts textual arguments into \texte{10,12}, i.e. characters whose catcodes are 10 ou 12:\par\medskip
+Here is an other ewample :\par\smallskip
\begin{minipage}[r]{0.6\linewidth}
\hfill
\begin{boxedverbatim}
- \edef\onecs{x y z}
- \scancs[1]\mycs\onecs
- \IfSubStr*{\mycs}{y}{true}{false}
+ \scancs[0]\mytext{abc}
+ \StrPosition{\mytext}{b}\par
+ \StrPosition*{\mytext}{b}\par
\end{boxedverbatim}
\hspace{0.3cm}
\end{minipage}%
\begin{minipage}[r]{0.3\linewidth}
- \edef\onecs{x y z}
- \scancs[1]\mycs\onecs
- \IfSubStr*{\mycs}{y}{true}{false}
-\end{minipage}
+ \scancs[0]\mytext{abc}
+ \StrPosition{\mytext}{b}\par
+ \StrPosition*{\mytext}{b}\par
+\end{minipage}\medskip
+
+The control sequence \verb|\mytext| contains \verb|{abc}| with catcodes 12 : indeed, \verb|\scancs| returns strings with catcodes 12 and 10 for space. Logically, the non-starred macro return 0 which means that it considers that the character ''\verb|b|${}_{11}$`` is not contained in the string ''\verb|a|${}_{12}$\verb|b|${}_{12}$\verb|c|${}_{12}$``. The starred macro behaves as expected and returns the correct position.\bigskip
+
+For the macros returning a string, if the starred version is used, the result will be a string with characters' catcode 12 and 10 fot space. For example, after ''\verb|\StrBefore*{a b c d}{c}[\mytext]|``, the expansion of the control sequence \verb|\mytext| will be ''\verb|a|${}_{12}$\verb*| |${}_{10}$\verb|b|${}_{12}$\verb*| |${}_{10}$``.
\subsection{Examples}
\label{exemples}
@@ -1273,7 +1379,7 @@ A control sequence \verb|\myCS| defined with an \verb|\edef| contains control se
\end{minipage}
\medskip
-Notice that 2 counters, 2 tests and a double recursion are necessary to find the group: one of each to find whiwh "\verb|}|" delimits the end of the current group, and the others to calculate the number of the group being read.\bigskip\bigskip
+Notice that 2 counters, 2 tests and a double recursion are necessary to find the group: one of each to find which "\verb|}|" delimits the end of the current group, and the others to calculate the number of the group being read.\bigskip\bigskip
\begin{center}
$\star$\par