Debian Codegraph @

texmf-dist/source/latex/stringstrings/stringstrings.dtx

raw
1 % \iffalse
2 %<package>\ProvidesPackage{stringstrings}
3 %<package>[2020/12/08 v1.24
4 %<package> Extensive array of string manipulation routines for
5 %<package> cosmetic and programming application]
6 %<package>\NeedsTeXFormat{LaTeX2e}
7 %<*driver>
8 % This work may be distributed and/or modified under the
9 % conditions of the LaTeX Project Public License, either version 1.3
10 % of this license or (at your option) any later version.
11 % The latest version of this license is in
12 % http://www.latex-project.org/lppl.txt
13 % and version 1.3c or later is part of all distributions of LaTeX
14 % version 2005/12/01 or later.
15 %
16 % This work has the LPPL maintenance status `maintained'.
17 %
18 % The Current Maintainer of this work is Steven B. Segletes.
19 %
20 % v1.00 -Initial Release
21 % v1.01 -Included support for & character, though it loses catcode 4
22 % status
23 % v1.02 -Bug fix. Needed some % chars in \convertchar to avoid extra spaces
24 % v1.03 -Documentation fix; notably removed 's' from \narg in \getargs
25 % v1.04 -Removed \rotate command, as it conflicts with environment in
26 % \usepackage{rotating}
27 % v1.10 -Fixed bug in convertword by adding @@@stringsize definition to
28 % \whereisword
29 % -Added suite of routines to support \capitalizetitle functionality
30 % v1.20 -Added ability to encode/decode arbitrary tokens
31 % v1.21 -Added %, removing extra space (bug) from \whereisword
32 % v1.22 -Added %, removing extra space (bug) from \getargs
33 % v1.23 -Changed {~} to {\ } in \retokenizechar
34 % -Forced all stringtest commands to function outside of math mode
35 % which will give correct result, when invoked within math mode.
36 % V1.24 -Added %, removing extra space (bug) from \testmatchingchar
37 \documentclass{ltxdoc}
38 \usepackage{stringstrings}
39 \DisableCrossrefs
40 \CodelineNumbered
41 % DEFINE SOME CAMMANDS THAT ARE EASIER HERE THAN IN DocInput ENVIRONMENT
42 \newcommand\stringstrings{\textsf{stringstrings}~}
43 \newcommand\coolstr{\textsf{coolstr}~}
44 % ITALICIZED i.e.,
45 \newcommand{\ie}{\textit{i.e.},~}%
46 % ITALICIZED e.g.,
47 \newcommand{\eg}{\textit{e.g.},~}%
48 % ITALICIZED etc.
49 \newcommand{\etc}{\textit{etc}.}%
50 \def\modetablelayout{|l|c|c|c|}
51 \def\mylayout{@{}c|c|l@{}}
52 \stringencode{\|}
53 \stringdecode[q]{\thestring}
54 \edef\mypipe{\thestring}
55 \stringencode{\carat}
56 \stringdecode[q]{\thestring}
57 \edef\mycarat{\thestring}
58
59 \GetFileInfo{stringstrings.sty}
60 \begin{document}
61 \title{The \stringstrings Package\\
62 \rule{0em}{0.7em}\small\fileinfo}
63 \author{Steven B. Segletes\\
64 [email protected]}
65 \date{\filedate\\
66 \fileversion}
67 \maketitle
68 \DocInput{stringstrings.dtx}
69 \end{document}
70 %</driver>
71 %\fi
72 % \parskip 1ex
73 % \begin{abstract}
74 % The \stringstrings package provides a large and sundry array of routines
75 % for the manipulation of strings. The routines are developed not only
76 % for cosmetic application, such as the changing of letter
77 % cases, selective removal of character classes, and string
78 % substitution,
79 % but also for programming application, such as character look-ahead
80 % applications, argument parsing, |\if|-tests for various string
81 % conditions, etc. A key tenet employed during the
82 % development of this package (unlike, for comparison, the |\uppercase|
83 % and |\lowercase| routines) was to have resultant strings be
84 % ``expanded'' (\ie the product of an |\edef|), so that the
85 % \stringstrings routines could be strung together sequentially and
86 % nested (after a fashion) to achieve very complex manipulations.
87 %
88 % \end{abstract}
89 %
90 % \vspace{-.55em}
91 % \tableofcontents\rule[.2em]{4.5in}{.3mm}\vspace{-1.5em}
92 %
93 % \section {Motivation}
94 %
95 % There were two seminal moments that brought about my motivation to
96 % develop this package. The first was the realization of the oft
97 % cited and infamous \LaTeX{} limitation concerning the inability to
98 % nest letter-case changes with \LaTeX{}'s intrinsic |\uppercase| and
99 % |\lowercase| routines. The second,
100 % though not diminishing its utility in many useful applications, was
101 % the inherent limitations of the \coolstr package, which is otherwise
102 % a useful tool for extracting substrings and measuring string lengths.
103 %
104 % The former is well documented and need not be delved into in great
105 % detail. Basically, as it was explained to me, |\uppercase| and
106 % |\lowercase| are expanded by \LaTeX{} at the last possible moment, and
107 % thus attempts to capture their result for subsequent use are doomed to
108 % failure. One is forced to adopt the left-to-right (rather than
109 % nested) approach to case changes.
110 %
111 % In the case of the \coolstr package, I again want to express
112 % my admiration for the utility of this package. I briefly considered
113 % building the \stringstrings package around it, but it proved
114 % unworkable, because of some intrinsic limitations.
115 % First, \coolstr operates on
116 % strings, not tokens, and so in order to fool it into working on
117 % tokenized inputs, one must use the cumbersome nomenclature of
118 %
119 % |\expandafter\substr\expandafter{\TokenizedString}{...}{...}|
120 % \vspace{1ex}\\%
121 % in order to, for example grab a substring of |\TokenizedString|. One
122 % may |\def| the result of this subroutine, and use it elsewhere in an
123 % unaltered state. However, one may not expand, via |\edef|, the
124 % result of |\substr| in order to use it as input to a subsequent string
125 % manipulation. And thus, the desire to engage in successive string
126 % manipulations of different natures (\eg capitalization of leading
127 % characters, extraction of words, reversal of character sequence,
128 % removal of character classes, etc., etc.) are not achievable in the
129 % context of \textsf{coolstr}.
130 %
131 % It was this state of affairs that brought me to hunger for routines
132 % that could thoroughly manipulate strings, and yet produce their result
133 % ``in the clear'' (\ie in an untokenized form) which could be used as
134 % input for the next manipulation. It turns out the heart of the
135 % \stringstrings package which achieves this goal is based on the simple
136 % (if much maligned) |\if| construct of \LaTeX{}, by using successive
137 % iterations of the following construct:
138 %
139 % |\if <|\textit{test char.}|><|\textit{string}|><|\textit{manipulated
140 % test char.}|>\else ...\fi|
141 % \vspace{1ex}\\%
142 % in which a character at the begining of a string is tested. If a
143 % match is found,
144 % the manipulated test character is replaced at the end of the string,
145 % while the original test character is lopped off from the beginning of
146 % the string. A false result is used to proceed to a different test
147 % character. In this manner, the string may be rotated through,
148 % character by character, performing the desired manipulations. And,
149 % most importantly, the product of this operation may be placed into an
150 % |\edef|.
151 %
152 % It turns out there was one glitch to this process (which has been
153 % successfully remedied in the \stringstrings package). And that is that
154 % there are several tokenized \LaTeX{} symbols (\eg |\$|, |\{|, |\}|,
155 % |\AE|, |\oe|, etc.) which expand to more than a single byte. If
156 % I was more savvy on \LaTeX{} constructs, I would probably have known
157 % how to handle this better. But my solution was to develop my own
158 % encoding scheme wherein these problematic characters were re-encoded
159 % in my intermediate calculations as a 2-byte (escape character-escape code)
160 % combination, and only converted back into \LaTeX{} symbols at the last
161 % moment, as the finalized strings were handed back to the user.
162 %
163 % There are also several tokens, like |\dag|, |\ddag|, |\P|, |\d|, |\t|,
164 % |\b|, and |\copyright| which
165 % can not be put into an |\edef| construct. The solution developed for
166 % strings containing these such characters was to convert the encoded
167 % string not into an expanded |\edef| construct, but rather back into a
168 % tokenized form amenable to |\def|. The |\retokenize| command
169 % accomplishes this task and several others.
170 %
171 % There was also one glitch that I have not yet been able to resolve
172 % to my full satisfaction, though I have provided a workaround.
173 % And that is the occurance of \LaTeX{} grouping characters, |{| and
174 % |}|, that might typically occur in math mode. The problem is that the
175 % character-rotate technique that is the core of \stringstrings breaks
176 % when rotating these group characters. Why?? Because a string
177 % comprised of |...{...}...|, during the rotation process, will
178 % eventually become |...}......{| during an intermediate stage of
179 % character rotation. This
180 % latter string breaks \LaTeX{} because it is not a properly constructed
181 % grouping, even if subsequent rotations would intend to bring it back
182 % into a proper construction.
183 %
184 % And so, while \stringstrings can handle certain math-mode
185 % constructs (\eg |$|, |^|, and |_|), it is unable to {\it directly}
186 % handle groupings that are brought about by the use of curly braces.
187 % Note that |\{| and |\}| are handled just fine, but not |{| and |}|.
188 % As a result of this limitation regarding the use of grouping braces
189 % within strings, \stringstrings support for various math symbols
190 % remains quite limited.
191 %
192 % While it is also common to use curly braces to
193 % delimit the arguments of diacritcal marks in words like
194 % |m\"{u}de| \etc, the same result can be achieved without the
195 % use of braces as |m\"ude|, with the proper result obtained: m\"ude.
196 % For diacritical marks that have an alphabetic token such as the breve,
197 % given by |\u|, the curly braces can also be omitted, with the only
198 % change being a space required after the |\u| to delimit the token.
199 % Thus, |c\u at| becomes c\u at. Therefore, when manipulating strings
200 % containing diacritical marks, it is best to formulate them, if
201 % possible, without the use of curly braces.
202 %
203 % The workaround fix I have developed, to provide grouping functions
204 % within \stringstrings arguments, involves the use of newly defined
205 % tokens |\LB| and |\RB| (to be used in lieu of |{| and |}|),
206 % along with a command |\retokenize|. This
207 % workaround will be described subsequently, in the Disclaimers section.
208 %
209 % \section{Philosophy of Operation}
210 %
211 % There are several classes of commands that have been developed as part
212 % of the \stringstrings package. In addition to {\bf Configuration
213 % Commands}, which set parameters for subsequent string operations,
214 % there are the following command classes:
215 % \begin{itemize}
216 % \item {\bf Commands to Manipulate Strings} -- these commands take an
217 % input string or token and perform a specific manipulation on the
218 % string;
219 % \item {\bf Commands to Extract String Information} -- these commands
220 % take an input string or token, and ascertain a particular
221 % characteristic of the string; and
222 % \item {\bf Commands to Test Strings} -- these commands take an input
223 % string or token and test for a particular alphanumeric condition.
224 % \end{itemize}
225 % Of course, there are also {\bf Support Commands} which are low-level
226 % routines which provide functionality to the package, which are
227 % generally not accessible to the user.
228 %
229 % To support the intended philosophy that the user may achieve a complex
230 % string manipulation though a series of simpler manipulations (which
231 % is otherwise known as nesting), a mechanism had to be developed. True
232 % command nesting of the form |\commandA{\commandB{\commandC{string}}}|
233 % is {\bf not} supported by the \stringstrings package, since many of
234 % the manipulation commands make use of (and would thus inadvertantly
235 % overwrite) the same sets of variables used by other routines.
236 % Furthermore, there is that 'ol left-to-right philosophy of \LaTeX{} to
237 % contend with.
238 %
239 % Instead, for the case of commands that manipulate strings, the expanded
240 % (\ie |\edef|'ed) result of the manipulation is placed into a string
241 % called |\thestring|\DescribeMacro{\thestring}. Then, |\thestring|
242 % may either be directly used
243 % as the input to a subsequent operation, or |\edef|'ed into another
244 % variable to save it for future use.
245 %
246 % String manipulation commands use an optional first argument to specify
247 % what to do with the manipulated string (in addition to putting it in
248 % |\thestring|). Most string manipulation
249 % commands default to verbose mode |[v]|\DescribeMacro{[v]}, and print
250 % out their result immediately on the assumption that a simple string
251 % manipulation is, many times, all that is required. If the user wishes
252 % to use the manipulated result as is, but needs to use it later in the
253 % document, a quiet mode |[q]| \DescribeMacro{[q]} is provided which
254 % suppresses the immediate output of |\thestring|.
255 %
256 % In the absence of symbol tokens (\eg |\$|, |\&|, |\oe|, |\^|, \etc),
257 % the verbose and quiet modes would prove sufficient. However, when a
258 % tokenized symbol is |\edef|'ed, the token is expanded to the actual
259 % symbolic representation of the character. If this expanded symbol is
260 % used as part of an input string to a
261 % subsequent \stringstrings manipulation
262 % routine, it gets confused, because the means to detect the token are
263 % characteristically different than the means to detect the expanded
264 % symbol. Thus, if one wishes to use |\thestring| as an input to a
265 % subsequent manipulation routine, \stringstrings provides an encoded
266 % mode |[e]| \DescribeMacro{[e]} which places an encoded version of the
267 % resulting manipulation into
268 % |\thestring|. The encoded mode is also a quiet mode, since it leaves
269 % |\thestring| in a visually unappealing state that is intended for
270 % subsequent manipulation.
271 %
272 % The encoded mode is not a \LaTeX{} standard,
273 % but was developed for this application. And therefore, if the result
274 % of a \stringstrings manipulation is needed as input for a routine
275 % outside of the \stringstrings package, the encoded mode will be of no
276 % use. For this reason (and others),
277 % the |\retokenize| \DescribeMacro{\retokenize}
278 % command is provided. Its use is one of only three times that a
279 % \stringstrings command
280 % returns a tokenized |\def|'ed string in |\thestring|, rather than an
281 % expanded, |\edef|'ed string. And in the other two cases, both
282 % call upon |\retokenize|.
283 %
284 % In addition to providing tokenized strings that can be passed to other
285 % \LaTeX{} packages, |\retokenize| can also remedy \stringstrings problems
286 % associated with inadequate character encodings (OT1) and the use of
287 % grouping characters |{| and |}| within \stringstrings arguments. This
288 % issue is discussed more fully in the Disclaimers section, and in the
289 % actual |\retokenize| command description.
290 %
291 % Therefore, for complex multistage string manipulations, the
292 % recommended procedure
293 % is to perform each stage of the manipulation in encoded |[e]| mode,
294 % passing along |\thestring| to each subsequent stage of the
295 % manipulation, until the very last manipulation, which should be,
296 % at the last, performed in verbose |[v]| or quiet |[q]| modes. If
297 % the resulting manipulation is to be passed to a command outside of the
298 % \stringstrings package for further manipulation (or if the string
299 % contains characters which cannot be placed into an |\edef|),
300 % |\thestring| may
301 % need to be |\retokenize|'ed. If concatenations of two (or more) different
302 % manipulations are to be used as input to a third manipulation,
303 % |\thestring| from the first manipulation will need to be immediately
304 % |\edef|'ed into a different variable, since |\thestring| will be
305 % overwritten by the second manipulation (see Table~\ref{tbl:modes}
306 % for summary).
307 % \begin{table}[h]
308 % \begin{center}
309 % \caption{\bf Execution Modes of \stringstrings Commands
310 % \label{tbl:modes}}\vspace{0.5em}
311 % \small
312 % \begin{tabular}\modetablelayout
313 % \hline
314 % Mode & Coding & Use when result is & |\thestring| is\\
315 % \hline
316 % \hline
317 % |[v]| verbose & decoded or retokenized & final & echoed \\
318 % |[q]| quiet & decoded or retokenized & final & not echoed \\
319 % |[e]| encoded & encoded & intermediate & not echoed \\
320 % \hline
321 % \end{tabular}
322 % \end{center}
323 % \end{table}
324 %
325 % Moving on to commands that extract string information, this class of
326 % commands (unless otherwise noted) output their result into a token
327 % which is given the name |\theresult|\DescribeMacro{\theresult}.
328 % This token does not contain a manipulated form of the string, but
329 % rather a piece of information about the string, such as ``how many
330 % characters are in the string?'', ``how many words are in the string?'',
331 % ``how many letter `e's are in the string?'', \etc
332 %
333 % The final class of \stringstrings commands are the string-test
334 % commands. While some of this class of commands also store their
335 % test result in |\theresult|, most of these commands use the
336 % |\test|{\it condition}|{|{\it string}|}| |\if|{\it
337 % condition} constructs (see {\sf ifthen} package) to answer true/false
338 % questions like ``is the string composed entirely of lowercase
339 % characters?'', ``is the string's first letter capitalized?'' \etc
340 %
341 % \section {Configuration Commands}
342 %
343 % \noindent%
344 % |\Treatments{|{\it U-mode}|}{|{\it l-mode}|}{|{\it p-mode}|}{|{\it%
345 % n-mode}|}{|{\it s-mode}|}{|{\it b-mode}|}|\\
346 % |\defaultTreatments|\\
347 % |\encodetoken[|{\it index}|]{|{\it token}|}|\\
348 % |\decodetoken[|{\it index}|]{|{\it token}|}|\\
349 % |\+|\\
350 % |\?|
351 %
352 % The command |\Treatments| \DescribeMacro{\Treatments}
353 % is used to define how different classes of
354 % characters are to be treated by the command |\substring|, which is the
355 % brains of the \stringstrings package. As will be explained in the
356 % next section, most string manipulation routines end up calling
357 % |\substring|, the difference between them being a matter of how these
358 % character treatments are set prior to the call.
359 % Because most string manipulation
360 % commands will set the treatments as necessary to perform their given
361 % task, and reset them to the default upon conclusion, one should set
362 % the |\Treatments| immediately prior to the call upon |\substring|.
363 %
364 % |\Treatments| has six arguments, that define the mode of treatment
365 % for the six classes of characters that \stringstrings has designated.
366 % All modes are one-digit integers. They are described below:
367 % \begin{itemize}
368 % \item{\it U-mode---} This mode defines the
369 % treatment for the upper-case characters (A--Z, \OE, \AE, \AA, \O, and
370 % \L).
371 % A mode of 0 tells |\substring| to remove upper-case characters, a
372 % mode of 1 indicates to leave upper-case characters alone, and
373 % a mode of 2 indicates to change the case of upper-case
374 % characters to lower case.
375 %
376 % \item {\it l-mode---} This mode defines the
377 % treatment for the lower-case characters (a--z, \oe, \ae, \aa, \o, \l,
378 % and \ss).
379 % A mode of 0 tells |\substring| to remove lower-case characters, a
380 % mode of 1 indicates to leave lower-case characters alone, and
381 % a mode of 2 indicates to change the case of lower-case
382 % characters to upper case. In the case of the eszett character (\ss),
383 % there is no uppercase equivalent, and so an {\it l-mode} of 2 will
384 % leave the eszett unchanged.
385 %
386 % \item {\it p-mode---} This mode defines the
387 % treatment for the punctuation characters. \stringstrings
388 % defines the punctuation characters as ; : ' " , . ? ` and ! A mode of
389 % 0 tells |\substring| to remove punctuation characters, while a mode of
390 % 1 indicates to leave punctuation characters as is.
391 %
392 % \item {\it n-mode---} This mode defines the
393 % treatment for the numerals (0--9). A mode of
394 % 0 tells |\substring| to remove numerals, while a mode of
395 % 1 indicates to leave numerals as is.
396 %
397 % \item {\it s-mode---} This mode defines the
398 % treatment for the symbols. \stringstrings
399 % defines symbols as the following characters and diacritical marks:
400 % \substring{/ * ( ) - = + [ ] $<$ $>$}{1}{$} \& |\& \% \# \{ \} \_ \$|
401 % \dag~\ddag~\S~\P~\L~\pounds~\copyright~\v x \^x \~x \"x \`x \'x \=x
402 % \.x \u x \v x
403 % \H x \c x \d x \t{xx} \b x as well as |@|, math and text carats,
404 % and the pipe symbol. A mode of
405 % 0 tells |\substring| to remove symbols, while a mode of
406 % 1 indicates to leave symbols as is. Note that the \$ symbol, when
407 % used for entering and exiting math mode, is left intact, regardless of
408 % {\it s-mode}.
409 %
410 % % \item {\it b-mode---} This mode defines the
411 % treatment for blankspaces. A mode of
412 % 0 tells |\substring| to remove blankspaces, while a mode of
413 % 1 indicates to leave blankspaces as is. The treatment apples to both
414 % soft (~) as well as hard (|~|) spaces.
415 % \end{itemize}
416 %
417 % The command |\defaultTreatments| \DescribeMacro{\defaultTreatments}
418 % resets all treatment modes to their default settings, which are to
419 % leave individual characters unaltered by a string manipulation.
420 %
421 % The commands |\encodetoken| \DescribeMacro{\encodetoken} and
422 % |\decodetoken| \DescribeMacro{\decodetoken} have been introduced in
423 % \stringstrings v1.20. Prior to this version, the ability of
424 % \stringstrings to handle a particular token was dependent on whether
425 % provisions for encoding that token had been explicitly hardwired into
426 % the \stringstrings package. A large number of alphabetic and
427 % diacritical marks had reserved encodings set aside in \stringstrings
428 % for their treatment (see next paragraph or Table 2 for their enumeration).
429 % However, requests would invariable come in for treating yet another
430 % token, which required a new \stringstrings release for each revision.
431 % The command |\encodetoken| allows the user to specify an arbitrary
432 % token, to be assigned to the reserved encoding slot associated with the
433 % index (permissible indices are in the range 1--3, 1 being the default).
434 % Once assigned an encoding slot, a token may be successfully manipulated in
435 % \stringstrings routines. Once \stringstrings manipulation is
436 % complete, the token must undergo a |\decodetoken| operation in order
437 % for that token to be reset to a normal \LaTeX{} token again (lest it
438 % display in its encoded \stringstrings form).
439 %
440 % The commands |\+| and |\?| \DescribeMacro{\+}\DescribeMacro{\?}
441 % are a pair that work in tandem to turn on \stringstrings encoding and
442 % turn off \stringstrings encoding, respectively. Generally, the user
443 % will not need these commands unless he is writing his own routines to
444 % take advantage of the \stringstrings library. After |\+| is called,
445 % tokens which would otherwise expand to multi-byte sequences are
446 % instead encoded according to the \stringstrings methodology. The
447 % affected tokens
448 % include
449 % |\$ \^ \" \{ \} \_ \dag \ddag \P \S \ss \AA \aa \O \o \AE \ae|
450 % |\OE|, |\oe|, |\~|, |\`|, |\'|, |\=|, |\.|, |\u|, |\v|, |\H|, |\c|,
451 % |\d|, |\t|, |\b|, |\copyright|, |\pounds|, |\L|, |\l|, and |\ss|. In
452 % addition, pipes, text carats, and hard spaces (|~|) are encoded
453 % as well. The command |\?| restores the
454 % standard \LaTeX{} encoding for these tokens.
455 %
456 % \section {Commands to Manipulate Strings}
457 %
458 % These commands take an
459 % input string or token and perform a specific manipulation on the
460 % string. They include:
461 %
462 % \noindent|\substring[|{\it mode}|]{|{\it
463 % string}|}{|{\it min}|}{|{\it max}|}|\\
464 % |\caseupper[|{\it mode}|]{|{\it string}|}|\\
465 % |\caselower[|{\it mode}|]{|{\it string}|}|\\
466 % |\solelyuppercase[|{\it mode}|]{|{\it string}|}|\\
467 % |\solelylowercase[|{\it mode}|]{|{\it string}|}|\\
468 % |\changecase[|{\it mode}|]{|{\it string}|}|\\
469 % |\noblanks[|{\it mode}|]{|{\it string}|}|\\
470 % |\nosymbolsnumerals[|{\it mode}|]{|{\it string}|}|\\
471 % |\alphabetic[|{\it mode}|]{|{\it string}|}|\\
472 % |\capitalize[|{\it mode}|]{|{\it string}|}|\\
473 % |\capitalizewords[|{\it mode}|]{|{\it string}|}|\\
474 % |\capitalizetitle[|{\it mode}|]{|{\it string}|}|\\
475 % |\addlcword{|{\it word}|}|\\
476 % |\addlcwords{|{\it word1 word2 word3 \ldots}|}|\\
477 % |\resetlcwords|\\
478 % |\reversestring[|{\it mode}|]{|{\it string}|}|\\
479 % |\convertchar[|{\it mode}|]{|{\it
480 % string}|}{|{\it from-char}|}{|{\it to-string}|}|\\
481 % |\convertword[|{\it mode}|]{|{\it
482 % string}|}{|{\it from-string}|}{|{\it to-string}|}|\\
483 % |\rotateword[|{\it mode}|]{|{\it string}|}|\\
484 % |\removeword[|{\it mode}|]{|{\it string}|}|\\
485 % |\getnextword[|{\it mode}|]{|{\it string}|}|\\
486 % |\getaword[|{\it mode}|]{|{\it string}|}{|{\it n}|}|\\
487 % |\rotateleadingspaces[|{\it mode}|]{|{\it string}|}|\\
488 % |\removeleadingspaces[|{\it mode}|]{|{\it string}|}|\\
489 % |\stringencode[|{\it mode}|]{|{\it string}|}|\\
490 % |\stringdecode[|{\it mode}|]{|{\it string}|}|\\
491 % |\gobblechar[|{\it mode}|]{|{\it string}|}|\\
492 % |\gobblechars[|{\it mode}|]{|{\it string}|}{|{\it n}|}|\\
493 % |\retokenize[|{\it mode}|]{|{\it string}|}|
494 %
495 % \noindent
496 % Unless otherwise noted, the {\it mode} may take one of three values:
497 % |[v]| for verbose mode (generally, the default), |[q]| for quiet mode,
498 % and |[e]| for encoded mode. In all cases, the result of
499 % the operation is stored in |\thestring|. In verbose mode, it is also
500 % output immediately (and may be captured by an |\edef|). In quiet mode,
501 % no string is output, though the result still resides in |\thestring|.
502 % Encoded mode is also a quiet mode. However, the encoded mode saves
503 % the string with its \stringstrings encodings. Encoded mode indicates
504 % that the result is an intermediate result which will be subsequently
505 % used as input to another \stringstrings manipulation.
506 %
507 % The command |\substring| \DescribeMacro{\substring} is the brains of
508 % the \stringstrings package, in that most of the commands in this
509 % section call upon |\substring| in one form or another. Nominally, the
510 % routine returns a substring of {\it string} between the characters
511 % defined by the integers {\it min} and {\it max}, inclusive.
512 % However, the returned substring is
513 % affected by the designated |\Treatments| which have been defined
514 % for various classes of characters. Additionally, a shorthand of \$
515 % may be used in {\it min} and {\it max} to define END-OF-STRING, and
516 % the shorthand \$--{\it integer} may be used to define an offset of
517 % {\it integer} relative to the END-OF-STRING.
518 %
519 % Regardless of how many bytes a \LaTeX{} token otherwise expands
520 % to, or how many characters are in the token name, each \LaTeX{}
521 % symbol token
522 % counts as a single character for the purposes of defining the
523 % substring limits, {\it min} and {\it max}.
524 %
525 % While the combination of |\Treatments| and |\substring| are sufficient
526 % to achieve a wide array of character manipulations, many of those
527 % possibilities are useful enough that separate commands have been
528 % created to describe them, for convenience. Several of the commands
529 % that follow fall into this category.
530 %
531 % The command |\caseupper| \DescribeMacro{\caseupper} takes the input
532 % string or token, and converts all lowercase characters in the string
533 % to uppercase. All other character classes are left untouched.
534 % Default mode is |[v]|.
535 %
536 % The command |\caselower| \DescribeMacro{\caselower} takes the input
537 % string or token, and converts all uppercase characters in the string
538 % to lowercase. All other character classes are left untouched.
539 % Default mode is |[v]|.
540 %
541 % The command |\solelyuppercase| \DescribeMacro{\solelyuppercase} is
542 % similar to |\caseupper|, except that all punctuation, numerals, and
543 % symbols are discarded from the string. Blankspaces are left alone,
544 % and lowercase characters are converted to uppercase.
545 % Default mode is |[v]|.
546 %
547 % The command |\solelylowercase| \DescribeMacro{\solelylowercase} is
548 % similar to |\caselower|, except that all punctuation, numerals, and
549 % symbols are discarded from the string. Blankspaces are left alone,
550 % and uppercase characters are converted to lowercase.
551 % Default mode is |[v]|.
552 %
553 % The command |\changecase| \DescribeMacro{\changecase} switches lower
554 % case to upper case and upper case to lower case. All other characters
555 % are left unchanged.
556 % Default mode is |[v]|.
557 %
558 % The command |\noblanks| \DescribeMacro{\noblanks} removes blankspaces
559 % (both hard and soft) from
560 % a string, while leaving other characters unchanged.
561 % Default mode is |[v]|.
562 %
563 % The command |\nosymbolsnumerals| \DescribeMacro{\nosymbolsnumerals}
564 % removes symbols and numerals from
565 % a string, while leaving other characters unchanged.
566 % Default mode is |[v]|.
567 %
568 % The command |\alphabetic| \DescribeMacro{\alphabetic} discards
569 % punctuation, symbols, and numerals, while retaining alphabetic
570 % characters and blankspaces.
571 % Default mode is |[v]|.
572 %
573 % The command |\capitalize| \DescribeMacro{\capitalize} turns the first
574 % character of {\it string} into its upper case, if it is alphabetic.
575 % Otherwise, that character will remain unaltered.
576 % Default mode is |[v]|.
577 %
578 % The command |\capitalizewords| \DescribeMacro{\capitalizewords} turns
579 % the first character of every word in {\it string} into its upper
580 % case, if it is alphabetic.
581 % Otherwise, that character will remain unaltered. For the purposes of
582 % this command, ``the first character of a word'' is defined as either
583 % the first character of the string, or the first non-blank
584 % character that follows one or more blankspaces.
585 % Default mode is |[v]|.
586 %
587 % The command |\capitalizetitle| \DescribeMacro{\capitalizetitle} is a
588 % command similar to |\capitalizewords|, except that words which have
589 % been previously designated as ``lower-case words'' are not
590 % capitalized (\eg prepositions, conjunctions, \etc). In all cases,
591 % the first word of the string is
592 % capitalized, even if it is on the lower-case word list. Words are
593 % added to the lower-case word list with the commands
594 % |\addlcword|\DescribeMacro{\addlcword}, in the case of a single word,
595 % or with |\addlcwords|\DescribeMacro{\addlcwords}, in the case of
596 % multiple (space-separated) words. Because the addition of many words
597 % to the lower-case list can substantially slow-down the execution of
598 % the |\capitalizetitle| command, the command
599 % |\resetlcwords| \DescribeMacro{\resetlcwords} has been added to
600 % allow the user to zero out the lower-case word list.
601 % (See newer \textsf{titlecaps} package as an alternative to this
602 % command.)
603 %
604 % The command |\reversestring| \DescribeMacro{\reversestring} reverses
605 % the sequence of characters in a string, such that what started as
606 % the first character becomes the last character in the manipulated
607 % string, and what started as the last character becomes the
608 % first character.
609 % Default mode is |[v]|.
610 %
611 % The command |\convertchar| \DescribeMacro{\convertchar} is a substitution
612 % command in which a specified match character in the original string
613 % ({\it from-char}) is substituted with a different string ({\it
614 % to-string}). All occurances of {\it from-char} in the original
615 % string are replaced. The {\it from-char} can only be a single
616 % character (or tokenized symbol), whereas {\it to-string} can range
617 % from the null-string (\ie character removal) to a single character
618 % (\ie character substitution)
619 % to a complete multi-character string.
620 % Default mode is |[v]|.
621 %
622 % The command |\convertword| \DescribeMacro{\convertword} is a substitution
623 % command in which a specified match string in the original string
624 % ({\it from-string}) is substituted with a different string ({\it
625 % to-string}). All occurances of {\it from-string} in the original
626 % string are replaced. If {\it from-string} includes spaces, use
627 % hard-space |(~)| characters instead of blanks.
628 % Default mode is |[v]|.
629 %
630 % The command |\rotateword| \DescribeMacro{\rotateword} takes the first
631 % word of {\it string} (and its leading and trailing spaces)
632 % and rotates them to the end of the string.
633 % Care must be taken to have a blankspace at the beginning or end
634 % of {\it string} if one wishes to retain a blankspace word
635 % separator between the original last word of the string and the
636 % original first word which has been rotated to the end of the string.
637 % Default mode is |[v]|.
638 %
639 % The command |\removeword| \DescribeMacro{\removeword} removes the
640 % first word of {\it string}, along with any of its leading and trailing
641 % spaces.
642 % Default mode is |[v]|.
643 %
644 % The command |\getnextword| \DescribeMacro{\getnextword} returns the
645 % next word of {\it string}. In this case, ``word'' is a sequence of
646 % characters delimited either by spaces or by the beginning or end
647 % of the string.
648 % Default mode is |[v]|.
649 %
650 % The command |\getaword| \DescribeMacro{\getaword} returns a
651 % word of {\it string} defined by the index, {\it n}.
652 % In this case, ``word'' is a sequence of
653 % characters delimited either by spaces or by the first or last
654 % characters of the string. If the index, {\it n}, requested exceeds the
655 % number of words available in the string, the index wraps around back
656 % to the first argument of the string, such that asking for the tenth word
657 % of an eight word string will return the second word of the string.
658 % Default mode is |[v]|.
659 %
660 % The command |\rotateleadingspaces|
661 % \DescribeMacro{\rotateleadingspaces} takes any leading spaces of the
662 % string and rotates them to the end of the string.
663 % Default mode is |[v]|.
664 %
665 % The command |\removeleadingspaces|
666 % \DescribeMacro{\removeleadingspaces} removes any leading spaces of the
667 % string.
668 % Default mode is |[v]|.
669 %
670 % The command |\stringencode| \DescribeMacro{\stringencode} returns a
671 % copy of the string that has been encoded according to the
672 % \stringstrings encoding scheme. Because an encoded string is an
673 % intermediate result, the default mode for this command is |[e]|.
674 %
675 % The command |\stringdecode| \DescribeMacro{\stringdecode} returns a
676 % copy of the string that has been decoded.
677 % Default mode is |[v]|.
678 %
679 % The command |\gobblechar| \DescribeMacro{\gobblechar} returns a string
680 % in which the first character of {\it string} has been removed. Unlike
681 % the \LaTeX{} system command |\@gobble| which removes the next {\bf
682 % byte} in
683 % the input stream, |\gobblechar| not only takes an argument as the
684 % target of its gobble, but also removes one {\bf character}, regardless
685 % of whether that character is a single-byte or multi-byte character.
686 % Because this command may have utility outside of the \stringstrings
687 % environment, the result of this command is retokenized (\ie |def|'ed)
688 % rather than expanded (\ie |edef|'ed).
689 % Default mode is |[q]|. Mode |[e]| is not recognized.
690 %
691 % The command |\gobblechars| \DescribeMacro{\gobblechars} returns a string
692 % in which the first {\it n} characters of {\it string} have been removed.
693 % Like |\gobblechar|, |\gobblechars| removes characters, regardless
694 % of whether those characters are single-byte or multi-byte characters.
695 % Likewise, the result of this command is retokenized (\ie |def|'ed)
696 % rather than expanded (\ie |edef|'ed).
697 % Default mode is |[q]|. Mode |[e]| is not recognized.
698 %
699 % The command |\retokenize| \DescribeMacro{\retokenize} takes a string
700 % that is encoded according to the \stringstrings encoding scheme, and
701 % repopulates the encoded characters with their \LaTeX{} tokens. This
702 % command is particularly useful for exporting a string to a routine
703 % outside of the \stringstrings library or if the string includes
704 % the following
705 % characters: |\{|, |\}|, \verb,\|,, |\dag|, |\ddag|, |\d|, |\t|, |\b|,
706 % |\copyright|, and |\P|.
707 % Default mode is |[q]|. Mode |[e]| is not recognized.
708 %
709 % \section {Commands to Extract String Information}
710 %
711 % These commands
712 % take an input string or token, and ascertain a particular
713 % characteristic of the string. They include:
714 %
715 % \noindent|\stringlength[|{\it mode}|]{|{\it string}|}|\\
716 % |\findchars[|{\it mode}|]{|{\it string}|}{|{\it match-char}|}|\\
717 % |\findwords[|{\it mode}|]{|{\it string}|}{|{\it match-string}|}|\\
718 % |\whereischar[|{\it mode}|]{|{\it string}|}{|{\it match-char}|}|\\
719 % |\whereisword[|{\it mode}|]{|{\it string}|}{|{\it match-string}|}|\\
720 % |\wordcount[|{\it mode}|]{|{\it string}|}|\\
721 % |\getargs[|{\it mode}|]{|{\it string}|}|
722 %
723 % \noindent Commands in this section return their result in the string
724 % |\theresult|, unless otherwise specified.
725 % Unless otherwise noted, the {\it mode} may take one of two values:
726 % |[v]| for verbose mode (generally, the default), and |[q]| for quiet
727 % mode. In both cases, the result of
728 % the operation is stored in |\theresult|. In verbose mode, it is also
729 % output immediately (and may be captured by an |\edef|). In quiet mode,
730 % no string is output, though the result still resides in |\theresult|.
731 %
732 % The command |\stringlength| \DescribeMacro{\stringlength} returns the
733 % length of {\it string} in characters (not bytes).
734 % Default mode is |[v]|.
735 %
736 % The command |\findchars| \DescribeMacro{\findchars} checks to see if
737 % the character {\it match-char} occurs anywhere in {\it string}. The
738 % number of occurances is stored in |\theresult| and, if in verbose
739 % mode, printed. If it is desired to find blankspaces, {\it match-char}
740 % should be set to |{~}| and not |{ }|.
741 % Default mode is |[v]|.
742 %
743 % The command |\findwords| \DescribeMacro{\findwords} checks to see if
744 % the string {\it match-string} occurs anywhere in {\it string}. The
745 % number of occurances is stored in |\theresult| and, if in verbose
746 % mode, printed. If it is desired to find blankspaces, those
747 % characters in {\it match-string}
748 % should be set to hardspaces (\ie tildes) and not softspaces (\ie
749 % blanks), regardless of how they are defined in {\it string}.
750 % Default mode is |[v]|.
751 %
752 % The command |\whereischar| \DescribeMacro{\whereischar} checks to see
753 % where
754 % the character {\it match-char} first occurs in {\it string}. The
755 % location of that occurance is stored in |\theresult| and, if in verbose
756 % mode, printed. If the character is not found, |\theresult| is set to
757 % a value of 0. If it is desired to find blankspaces, {\it match-char}
758 % should be set to |{~}| and not |{ }|.
759 % Default mode is |[v]|.
760 %
761 % The command |\whereisword| \DescribeMacro{\whereisword} checks to see
762 % where
763 % the string {\it match-string} first occurs in {\it string}. The
764 % location of that occurance is stored in |\theresult| and, if in verbose
765 % mode, printed. If {\it match-string} is not found, |\theresult| is set to
766 % a value of 0. If it is desired to find blankspaces, those characters
767 % in {\it match-string}
768 % should be set to hardspaces (\ie tildes) and not softspaces (\ie
769 % blanks), regardless of how they are defined in {\it string}.
770 % Default mode is |[v]|.
771 %
772 % The command |\wordcount| \DescribeMacro{\wordcount} counts the number
773 % of space-separated words that occur in {\it string}.
774 % Default mode is |[v]|.
775 %
776 % The command |\getargs| \DescribeMacro{\getargs} mimics the Unix
777 % command of the same name, in that it parses {\it string} to determine
778 % how many arguments (\ie words) are in {\it string}, and extracts
779 % each word into a separate variable. The number of arguments is placed
780 % in |\narg| and the individual arguments are placed in variables of
781 % the name |\argi|, |\argii|, |\argiii|, |\argiv|, etc. This command
782 % may be used to facilitate simply the use of multiple optional
783 % arguments in a \LaTeX{} command, for example
784 % |\mycommand[|{\it option1 option2 option3}|]{|{\it argument}|}|.
785 % In this case,
786 % |\mycommand| should exercise |\getargs{#1}|, with the result being
787 % that {\it option1} is stored in |\argi|, \etc~The command |\mycommand|
788 % may then proceed to parse the optional arguments and branch
789 % accordingly.
790 % Default mode is |[q]|; |[e]| mode is permitted, while |[v]| mode
791 % is disabled.
792 %
793 % \section {Commands to Test Strings}
794 %
795 % These commands take an input
796 % string or token and test for a particular alphanumeric condition.
797 % They include:
798 %
799 % \noindent%
800 % |\isnextbyte[|{\it mode}|]{|{\it match-byte}|}{|{\it string}|}|\\
801 % |\testmatchingchar{|{\it
802 % string}|}{|{\it n}|}{|{\it match-char}|}|\\
803 % |\testcapitalized{|{\it string}|}|\\
804 % |\testuncapitalized{|{\it string}|}|\\
805 % |\testleadingalpha{|{\it string}|}|\\
806 % |\testuppercase{|{\it string}|}|\\
807 % |\testsolelyuppercase{|{\it string}|}|\\
808 % |\testlowercase{|{\it string}|}|\\
809 % |\testsolelylowercase{|{\it string}|}|\\
810 % |\testalphabetic{|{\it string}|}|
811 %
812 % The command |\isnextbyte| \DescribeMacro{\isnextbyte} tests to see if
813 % the first byte of {\it string} equals {\it match-byte}. It
814 % is the only string-testing command in
815 % this section which does not use the {\sf ifthen} test structure for
816 % its result. Rather, |\isnextbyte| returns the result of its test as
817 % a |T| or |F| in the string |\theresult|. More importantly, and
818 % unlike other \stringstrings commands, |\isnextbyte| is a {\it byte} test
819 % and not a {\it character} test. This means that, while |\isnextbyte|
820 % operates very efficiently, it cannot
821 % be used to directly detect multi-byte characters like |\$|,
822 % |\^|, |\{|, |\}|, |\_|, |\dag|, |\ddag|, |\AE|, |\ae|, |\OE|,
823 % |\oe|, \etc~(|\isnextbyte| will give false positives or negatives
824 % when testing for these multi-byte characters).
825 % The default mode of |\isnextbyte| is |[v]|.
826 %
827 % If a character needs to be tested, rather than a byte,
828 % \DescribeMacro{\testmatchingchar} |\testmatchingchar| should be used.
829 % The command |\testmatchingchar| is
830 % used to ascertain whether character {\it n} of {\it string} equals
831 % {\it match-char} or not. Whereas |\isnextbyte| checks only a {\it
832 % byte}, |\testmatchingchar| tests for a {\it character} (single- or
833 % multi-byte character). After the test is called, the action(s) may be
834 % called out with |\ifmatchingchar| {\it true-code} |\else| {\it
835 % false-code} |\fi|.
836 %
837 % The command |\testcapitalized| \DescribeMacro{\testcapitalized} is
838 % used to ascertain whether the first character of {\it string} is
839 % capitalized or not. If the first character is non-alphabetic, the
840 % test will return FALSE. After the test is called, the action(s) may be
841 % called out with |\ifcapitalized| {\it true-code} |\else| {\it
842 % false-code} |\fi|.
843 %
844 % The command |\testuncapitalized| \DescribeMacro{\testuncapitalized} is
845 % used to ascertain whether the first character of {\it string} is
846 % uncapitalized. If the first character is non-alphabetic, the
847 % test will return FALSE. After the test is called, the action(s) may be
848 % called out with |\ifuncapitalized| {\it true-code} |\else| {\it
849 % false-code} |\fi|.
850 %
851 % The command |\testleadingalpha| \DescribeMacro{\testleadingalpha} is
852 % used to ascertain whether the first character of {\it string} is
853 % alphabetic. After the test is called, the action(s) may be
854 % called out with |\ifleadingalpha| {\it true-code} |\else| {\it
855 % false-code} |\fi|.
856 %
857 % The command |\testuppercase| \DescribeMacro{\testuppercase} is
858 % used to ascertain whether all the alphabetic characters in {\it
859 % string} are uppercase or not. The presence of non-alphabetic
860 % characters in {\it string} does not falsify the test,
861 % but are merely ignored. However, a string completely void of
862 % alphabetic characters will always test FALSE.
863 % After the test is called, the action(s) may be
864 % called out with |\ifuppercase| {\it true-code} |\else| {\it
865 % false-code} |\fi|.
866 %
867 % The command |\testsolelyuppercase|
868 % \DescribeMacro{\testsolelyuppercase} is
869 % used to ascertain whether {\it all} the characters in {\it
870 % string} are uppercase or not. The presence of non-alphabetic
871 % characters in {\it string} other than blankspaces will automatically
872 % falsify the test. Blankspaces are ignored. However, a null string or
873 % a string composed solely of blankspaces will also test FALSE.
874 % After the test is called, the action(s) may be
875 % called out with |\ifsolelyuppercase| {\it true-code} |\else| {\it
876 % false-code} |\fi|.
877 %
878 % The command |\testlowercase| \DescribeMacro{\testlowercase} is
879 % used to ascertain whether all the alphabetic characters in {\it
880 % string} are lowercase or not. The presence of non-alphabetic
881 % characters in {\it string} does not falsify the test,
882 % but are merely ignored. However, a string completely void of
883 % alphabetic characters will always test FALSE.
884 % After the test is called, the action(s) may be
885 % called out with |\iflowercase| {\it true-code} |\else| {\it
886 % false-code} |\fi|.
887 %
888 % The command |\testsolelylowercase|
889 % \DescribeMacro{\testsolelylowercase} is
890 % used to ascertain whether {\it all} the characters in {\it
891 % string} are lowercase or not. The presence of non-alphabetic
892 % characters in {\it string} other than blankspaces will automatically
893 % falsify the test. Blankspaces are ignored. However, a null string or
894 % a string composed solely of blankspaces will also test FALSE.
895 % After the test is called, the action(s) may be
896 % called out with |\ifsolelylowercase| {\it true-code} |\else| {\it
897 % false-code} |\fi|.
898 %
899 % The command |\testalphabetic|
900 % \DescribeMacro{\testalphabetic} is
901 % used to ascertain whether {\it all} the characters in {\it
902 % string} are alphabetic or not. The presence of non-alphabetic
903 % characters in {\it string} other than blankspaces will automatically
904 % falsify the test. Blankspaces are ignored. However, a null string or
905 % a string composed solely of blankspaces will also test FALSE.
906 % After the test is called, the action(s) may be
907 % called out with |\ifalphabetic| {\it true-code} |\else| {\it
908 % false-code} |\fi|.
909 %
910 % \section{Disclaimers}
911 %
912 % Now that we have described the commands available in the
913 % \stringstrings package, it is appropriate to lay out the quirks and
914 % warnings associated with the use of the package.
915 %
916 % First, \stringstrings is currently set to handle a string no larger
917 % than 500 characters. A user could circumvent this, presumably, by
918 % editing the style package to increase the value of
919 % |\@MAXSTRINGSIZE| \DescribeMacro{\@MAXSTRINGSIZE}.
920 %
921 % It is important to remember that \stringstrings follows the underlying
922 % rules of \LaTeX{}. Therefore, a passed string could not contain a raw
923 % |%| as part of it, because it would, in fact, comment out the
924 % remainder of the line. Naturally, the string may freely contain
925 % instances of |\%|.
926 %
927 % Tokens that take two or more characters to express
928 % (\eg |\#|, |\oe|, |\ddag|, \etc) are {\bf counted as
929 % a single character} within the string.
930 % The rule applies if you wanted to know the length
931 % of a string that was populated with such tokens, or wanted to extract
932 % a substring from a such a string. Of course, the exception that makes
933 % the rule is that of diacritical marks, which count as separate symbols
934 % from the characters they mark. For example,
935 % |\^a| counts as two characters, because the |a| is
936 % really just the operand of the |\^| token, even though the net result
937 % looks like a single character (\^a).
938 %
939 % Consistent with
940 % \LaTeX{} convention, groups of spaces are treated as a single
941 % blankspace, unless encoded with |~| characters. And finally, again
942 % consistent with the way \LaTeX{} operates, the space
943 % that follows an alphabetic token is not actually a space in the
944 % string, but serves as the delimiter to the token. Therefore,
945 % |\OE dipus| (\OE dipus) has a length of six characters,
946 % one for the |\OE| and five
947 % for the |dipus|. The intervening space merely closes out the |\OE|
948 % token, and does not represent a space in the middle of the string.
949 %
950 % One quirk worthy of particular note concerns the tabbing character,
951 % meaning \&
952 % as opposed to |\&| (which is handled without problem).
953 % As of version 1.01, \stringstrings has the
954 % capability to operate on arguments containg the ampersand \&,
955 % normally reserved as the \LaTeX{} tabbing character. However, one
956 % adverse by-product is that \& characters returned in |\thestring|
957 % lose their catcode-4 value, and thus lose their ability to function as
958 % tabbing characters. In the following example,\\
959 % | |\\
960 % | \caseupper[q]{a & b & c & d}|\\
961 % | \begin{tabular}{|\verb,|l|c|c|c|,|}|\\
962 % | \hline|\\
963 % | \thestring\\|\\
964 % | \hline|\\
965 % | \end{tabular}|\\
966 % | |\\
967 % will produce \caseupper[q]{a & b & c & d}
968 % \begin{tabular}{\modetablelayout}
969 % \hline
970 % \thestring\\
971 % \hline
972 % \end{tabular}
973 % instead of the desired
974 % \begin{tabular}{\modetablelayout}
975 % \hline
976 % A & B & C & D\\
977 % \hline
978 % \end{tabular}
979 % .
980 %
981 % In the |\substring| command, no tests are performed to guarantee that
982 % the lower limit, {\it min}, is less than the upper limit, {\it max},
983 % or that {\it min} is even positive. However, the upper limit,
984 % {\it max}, is corrected, if set larger than the string length. Also,
985 % the use of the `\$' symbol to signify the last character of the string
986 % and `\$--{\it n}' to denote an offset of {\it n} characters from the
987 % end of the string can be helpful in avoiding the misindexing of strings.
988 %
989 % \begin{table}[p]
990 % \caption{\bf Problematic Characters/Tokens and \stringstrings Solutions%
991 % \label{tbl:prob}}\vspace{.5em}
992 % \small
993 % \begin{tabular}{\mylayout}
994 % \LaTeX{} & Symbol/Name & Problem/Solution\\
995 % \hline
996 % \hline
997 % |{| & begin group & Cannot use |{| and |}| in \stringstrings
998 % arguments.\\
999 % |}| & end group & However, use |\LB|\ldots|\RB| in lieu of |{|\ldots|}|;\\
1000 % & & manipulate string in |[e]| mode \& |\retokenize| \\
1001 % \hline
1002 % |\dag| & \dag~~Dagger & Cannot |\edef| these tokens; Thus, |[v]| mode\\
1003 % |\ddag| & \ddag~~Double Dagger & fails with both OT1 and T1 encoding; \\
1004 % |\P| & \P~~Pilcrow & manipulate string in |[e]| mode \& |\retokenize| \\
1005 % |\d| & \d x~~Underdot & \\
1006 % |\t| & \t xx~~Joining Arch & \\
1007 % |\b| & \b x~~Letter Underline & \\
1008 % |\copyright| & \copyright~Copyright & \\
1009 % \hline
1010 % \hline
1011 % |\_| & \_~~Underscore & Cannot |\edef| with OT1 encoding; either\\
1012 % |\{| & \{~~Left Curly Brace & |\renewcommand\encodingdefault{T1}|, or \\
1013 % |\}| & \}~~Right Curly Brace &
1014 % manipulate string in |[e]| mode \& |\retokenize|. \\
1015 % |\S| & \S~~Section Symbol & With OT1, |\S|, |\c| and |\pounds| break\\
1016 % |\c| & \c x~~Cedilla & \stringstrings |[v]| mode.\\
1017 % |\pounds| & \pounds~~Pounds & \\
1018 % \hline
1019 % \verb,\|,& \stringstrings Pipe Char. & Distinct from \verb,|,,
1020 % the \stringstrings encoded-\\
1021 % & \verb,|, (T1) ~~~\stringdecode{\|} (OT1) & escape character\\
1022 % \hline
1023 % \hline
1024 % |\$| & \$~~Dollar & Either cannot |\edef|, or\\
1025 % |\carat| & \mycarat~~(text mode) &
1026 % cannot identify uniquely with |\if| construct, or \\
1027 % |\^| & \^x~~Circumflex & expanded character is more than one byte. \\
1028 % |\'| & \'x~~Acute & \\
1029 % |\"| & \"x~~Umlaut & {\it However},\\
1030 % |\~| & \~x~~Tilde &
1031 % Use these characters freely, \stringstrings\\
1032 % |\`| & \`x~~Grave &
1033 % encoding functions transparently with them.\\
1034 % |\.| & \.x~~Overdot & \\
1035 % |\=| & \=x~~Macron & |\retokenize| also works\\
1036 % |\u| & \u x~~Breve & \\
1037 % |\v| & \v x~~Caron & \\
1038 % |\H| & \H x~~Double Acute & \\
1039 % |\ss| & \ss~~Eszett & \\
1040 % |\AE \ae| & \AE~\ae~~\ae sc & \\
1041 % |\OE \oe| & \OE~\oe~~\oe thel & \\
1042 % |\AA \aa| & \AA~\aa~~angstrom & \\
1043 % |\O \o| & \O~\o~~slashed O & \\
1044 % |\L \l| & \L~\l~~barred L & \\
1045 % |~| & Hardspace &\\
1046 % \hline
1047 % |$| & begin/end math mode & These characters pose no difficulties;\\
1048 % |^| & math superscript & However, cannot extract substring that \\
1049 % |_| & math subscript & breaks in middle of math mode.\\
1050 % & & Other math mode symbols NOT supported.\\
1051 % \hline
1052 % \& & ampersand & Version 1.01 \stringstrings can manipulate the\\
1053 % & & ampersand. However, returned strings\\
1054 % & & containing the \& character lose their\\
1055 % & & catcode-4 status, making them unfit\\
1056 % & & for use as tabbing characters.\\
1057 % \hline
1058 % \hline
1059 % \end{tabular}
1060 % \end{table}
1061 % Table~\ref{tbl:prob} shows a variety of characters and tokens, some of
1062 % which pose a challenge to \stringstrings manipulations. In all cases,
1063 % a solution or workaround is provided. For symbols in the top two
1064 % categories, the workaround
1065 % solution includes the use of retokenized strings instead of expanded
1066 % strings. For symbols in the next two categories, use of T1 encoding
1067 % or retokenizing provides a satisfactory solution. In the bottom three
1068 % categories, because of \stringstrings encoded |[e]| mode,
1069 % there is nothing to impede the use of these characters in
1070 % \stringstrings arguments, if encoded |[e]| mode is employed for
1071 % intermediate calculations. Some of the
1072 % details of these problematic cases is described below.
1073 %
1074 % Not surprisingly, you are not allowed to extract a substring of a
1075 % string, if it breaks in the middle of math mode, because a substring
1076 % with only one |$| in it cannot be |\edef|'ed.
1077 %
1078 % There are a few potential quirks when using \LaTeX{}'s native OT1
1079 % character encoding, most of which can be circumvented by using the
1080 % more modern
1081 % T1 encoding (accessed via |\renewcommand\encodingdefault{T1}| in the
1082 % document preamble). The quirks arise because there are
1083 % several characters that, while displayable in \LaTeX{}, are not part
1084 % of the OT1 character encoding. The characters include |\{|, |\}|, and
1085 % the \verb,|, symbol (accessed in \stringstrings via \verb,\|,).
1086 % When using \stringstrings to manipulate strings containing
1087 % these characters in the presence of OT1 encoding,
1088 % they come out looking like \stringdecode{\{}, \stringdecode{\}},
1089 % and \stringdecode{\|}, respectively. However, if the T1 encoding fix
1090 % is not an option for you, you can also work around this problem by
1091 % |\retokenize|'ing the affected string (the |\retokenize| command is
1092 % provided to convert encoded, expanded strings back into tokenized
1093 % form, if need be).
1094 %
1095 % Likewise, for both OT1 and T1 encoding, the characters \dag~(|\dag|),
1096 % \ddag~(|\ddag|), \P~(|\P|), \d~~(|\d|), \t~~~(|\t|), \b~~~(|\b|),
1097 % and \copyright~(|\copyright|)
1098 % cannot be in the argument of an |\edef| expression. For
1099 % manipulated strings including these characters, |\retokenize| is the
1100 % only option available to retain the integrity of the string.
1101 %
1102 % As discussed thoroughly in the previous section, an ``encoded'' form of
1103 % the string manipulation routines is provided to prevent the
1104 % undesirable circumstance of passing an |\edef|'ed symbol as input
1105 % to a subsequent manipulation. Likewise, never try to ``decode''
1106 % an already ``decoded'' string.
1107 %
1108 % When \stringstrings doesn't understand a token, it is supposed to
1109 % replace it with a period. However, some undecipherable characters may
1110 % inadvertantly be replaced with a space, instead. Of course, neither
1111 % of these possibilities is any comfort to the user.
1112 %
1113 % As mentioned already, \stringstrings cannot handle curly braces that
1114 % are used for grouping purposes, a circumstance which often arises in
1115 % math mode. Nonetheless, |\LB| and |\RB| may be used within
1116 % \stringstrings arguments in lieu of grouping braces, {\it if the final
1117 % result is to be retokenized}. Thus, |\caselower[e]{$X^\LB Y + Z\RB$}|
1118 % followed by |\convertchar[e]{\thestring}{x}{(1+x)}|, when finished up
1119 % with the following command,
1120 % |\retokenize[v]{\thestring}| yields as its result:\\
1121 % \caselower[e]{$X^\LB Y + Z\RB$}\convertchar[e]{\thestring}{x}{(1+x)}
1122 % \retokenize[v]{\thestring}.
1123 %
1124 % One might ask, ``why not retokenize everything, instead of using the
1125 % |[v]| mode of the \stringstrings routines?'' While one {\it could}
1126 % do this, the answer is simply
1127 % that |\retokenize| is a computationally intensive command, and that
1128 % it is best used, therefore, only when the more efficient methods
1129 % will not suffice. In many, if not most cases, strings to be
1130 % manipulated will be solely composed of alphanumeric characters which
1131 % don't require the use of |\retokenize|, T1 encoding, or even
1132 % \stringstrings encoding.
1133 %
1134 % Despite these several disclaimers and workarounds required when
1135 % dealing with problematic characters, I hope you find the \stringstrings
1136 % architecture and feel to be straightforward and useful. There is only
1137 % one thing left, and that is to dissect the code\ldots and so here we
1138 % go.
1139 %
1140 %% \CharacterTable
1141 %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
1142 %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
1143 %% Digits \0\1\2\3\4\5\6\7\8\9
1144 %% Exclamation \! Double quote \" Hash (number) \#
1145 %% Dollar \$ Percent \% Ampersand \&
1146 %% Acute accent \' Left paren \( Right paren \)
1147 %% Asterisk \* Plus \+ Comma \,
1148 %% Minus \- Point \. Solidus \/
1149 %% Colon \: Semicolon \; Less than \<
1150 %% Equals \= Greater than \> Question mark \?
1151 %% Commercial at \@ Left bracket \[ Backslash \\
1152 %% Right bracket \] Circumflex \^ Underscore \_
1153 %% Grave accent \` Left brace \{ Vertical bar \|
1154 %% Right brace \} Tilde \~}
1155 % \StopEventually{}
1156 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1157 % \vspace{-0.8em}
1158 % \begin{macro}{stringstrings.sty}
1159 % \section{Code Listing}
1160 % I'll try to lay out herein
1161 % the workings of the \stringstrings style package.
1162 % \begin{macrocode}
1163 %<*package>
1164
1165 %%%%% INITIALIZATIONS %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1166 \catcode`\&=12
1167 % \end{macrocode}
1168 % \end{macro}
1169 %
1170 % \begin{macro}{ifthen}
1171 % This package makes wide use of the {\sf ifthen} style package.
1172 % \begin{macrocode}
1173 \usepackage{ifthen}
1174 % \end{macrocode}
1175 % \end{macro}
1176
1177 % \begin{macro}{\@MAXSTRINGSIZE}
1178 % The parameter |\@MAXSTRINGSIZE| defines the maximum allowable string
1179 % size that \stringstrings can operate upon.
1180 % \begin{macrocode}
1181 \def\@MAXSTRINGSIZE{500}
1182 % \end{macrocode}
1183 % \end{macro}
1184
1185 % \begin{macrocode}
1186 \def\endofstring{@E@o@S@}%
1187 \def\undecipherable{.}% UNDECIPHERABLE TOKENS TO BE REPLACED BY PERIOD
1188 \def\@blankaction{\BlankSpace}
1189 % \end{macrocode}
1190 % Save the symbols which will get redefined \stringstrings encoding.
1191
1192 % \begin{macrocode}
1193 \let\SaveDollar\$
1194 \let\SaveHardspace~
1195 \let\SaveCircumflex\^
1196 \let\SaveTilde\~
1197 \let\SaveUmlaut\"
1198 \let\SaveGrave\`
1199 \let\SaveAcute\'
1200 \let\SaveMacron\=
1201 \let\SaveOverdot\.
1202 \let\SaveBreve\u
1203 \let\SaveCaron\v
1204 \let\SaveDoubleAcute\H
1205 \let\SaveCedilla\c
1206 \let\SaveUnderdot\d
1207 \let\SaveArchJoin\t
1208 \let\SaveLineUnder\b
1209 \let\SaveCopyright\copyright
1210 \let\SavePounds\pounds
1211 \let\SaveLeftBrace\{
1212 \let\SaveRightBrace\}
1213 \let\SaveUnderscore\_
1214 \let\SaveDagger\dag
1215 \let\SaveDoubleDagger\ddag
1216 \let\SaveSectionSymbol\S
1217 \let\SavePilcrow\P
1218 \let\SaveAEsc\AE
1219 \let\Saveaesc\ae
1220 \let\SaveOEthel\OE
1221 \let\Saveoethel\oe
1222 \let\SaveAngstrom\AA
1223 \let\Saveangstrom\aa
1224 \let\SaveSlashedO\O
1225 \let\SaveSlashedo\o
1226 \let\SaveBarredL\L
1227 \let\SaveBarredl\l
1228 \let\SaveEszett\ss
1229 \let\SaveLB{
1230 \let\SaveRB}
1231 % \end{macrocode}
1232
1233 % The BlankSpace character is the only character which is reencoded
1234 % with a 1-byte re-encoding\ldots in this case the \OE~character.
1235 % \begin{macrocode}
1236 \def\EncodedBlankSpace{\SaveOEthel}
1237 \edef\BlankSpace{ }
1238 % \end{macrocode}
1239 % All other reencoded symbols consist of 2 bytes: an escape character
1240 % plus a unique code. The escape character is a pipe symbol. the
1241 % unique code comprises either a single number, letter, or symbol.
1242
1243 % \begin{macrocode}
1244 \def\EscapeChar{|}
1245
1246 % |0 IS AN ENCODED |, ACCESSED VIA \|
1247 \def\PipeCode{0}
1248 \def\EncodedPipe{\EscapeChar\PipeCode}
1249 \def\Pipe{|}
1250 \let\|\EncodedPipe
1251
1252 % |1 IS AN ENCODED \$
1253 \def\DollarCode{1}
1254 \def\EncodedDollar{\EscapeChar\DollarCode}
1255 % THE FOLLOWING IS NEEDED TO KEEP OT1 ENCODING FROM BREAKING;
1256 % IT PROVIDES AN ADEQUATE BUT NOT IDEAL ENVIRONMENT FOR T1 ENCODING
1257 \def\Dollar{\symbol{36}}
1258 % THE FOLLOWING IS BETTER FOR T1 ENCODING, BUT BREAKS OT1 ENCODING
1259 %\def\Dollar{\SaveDollar}
1260
1261 % |W IS RESERVED TO BE ASSIGNED TO AN ARBITRARY TOKEN
1262 \def\UvariCode{W}
1263 \def\EncodedUvari{\EscapeChar\UvariCode}
1264 \def\Uvari{Uvari}
1265 \let\uvari\EncodedUvari
1266
1267 % |X IS RESERVED TO BE ASSIGNED TO AN ARBITRARY TOKEN
1268 \def\UvariiCode{X}
1269 \def\EncodedUvarii{\EscapeChar\UvariiCode}
1270 \def\Uvarii{Uvarii}
1271 \let\uvarii\EncodedUvarii
1272
1273 % |Y IS RESERVED TO BE ASSIGNED TO AN ARBITRARY TOKEN
1274 \def\UvariiiCode{Y}
1275 \def\EncodedUvariii{\EscapeChar\UvariiiCode}
1276 \def\Uvariii{Uvariii}
1277 \let\uvariii\EncodedUvariii
1278
1279 % |2 IS AN ENCODED ^ FOR USE IN TEXT MODE, ACCESSED VIA \carat
1280 \def\CaratCode{2}
1281 \def\EncodedCarat{\EscapeChar\CaratCode}
1282 \def\Carat{\symbol{94}}
1283 \let\carat\EncodedCarat
1284
1285 % |4 IS AN ENCODED \{
1286 \def\LeftBraceCode{4}
1287 \def\EncodedLeftBrace{\EscapeChar\LeftBraceCode}
1288 % THE FOLLOWING IS NEEDED TO KEEP OT1 ENCODING FROM BREAKING;
1289 % IT PROVIDES AN ADEQUATE BUT NOT IDEAL ENVIRONMENT FOR T1 ENCODING
1290 \def\LeftBrace{\symbol{123}}
1291 % THE FOLLOWING IS BETTER FOR T1 ENCODING, BUT BREAKS OT1 ENCODING
1292 %\def\LeftBrace{\SaveLeftBrace}
1293
1294 % |5 IS AN ENCODED \}
1295 \def\RightBraceCode{5}
1296 \def\EncodedRightBrace{\EscapeChar\RightBraceCode}
1297 % THE FOLLOWING IS NEEDED TO KEEP OT1 ENCODING FROM BREAKING;
1298 % IT PROVIDES AN ADEQUATE BUT NOT IDEAL ENVIRONMENT FOR T1 ENCODING
1299 \def\RightBrace{\symbol{125}}
1300 % THE FOLLOWING IS BETTER FOR T1 ENCODING, BUT BREAKS OT1 ENCODING
1301 %\def\RightBrace{\SaveRightBrace}
1302
1303 % |6 IS AN ENCODED \_
1304 \def\UnderscoreCode{6}
1305 \def\EncodedUnderscore{\EscapeChar\UnderscoreCode}
1306 \def\Underscore{\symbol{95}}
1307 %\def\Underscore{\SaveUnderscore}
1308
1309 % |7 IS AN ENCODED \^
1310 \def\CircumflexCode{7}
1311 \def\EncodedCircumflex{\EscapeChar\CircumflexCode}
1312 \def\Circumflex{\noexpand\SaveCircumflex}
1313
1314 % |8 IS AN ENCODED \~
1315 \def\TildeCode{8}
1316 \def\EncodedTilde{\EscapeChar\TildeCode}
1317 \def\Tilde{\noexpand\SaveTilde}
1318
1319 % |" IS AN ENCODED \"
1320 \def\UmlautCode{"}
1321 \def\EncodedUmlaut{\EscapeChar\UmlautCode}
1322 \def\Umlaut{\noexpand\SaveUmlaut}
1323
1324 % |` IS AN ENCODED \`
1325 \def\GraveCode{`}
1326 \def\EncodedGrave{\EscapeChar\GraveCode}
1327 \def\Grave{\noexpand\SaveGrave}
1328
1329 % |' IS AN ENCODED \'
1330 \def\AcuteCode{'}
1331 \def\EncodedAcute{\EscapeChar\AcuteCode}
1332 \def\Acute{\noexpand\SaveAcute}
1333
1334 % |= IS AN ENCODED \=
1335 \def\MacronCode{=}
1336 \def\EncodedMacron{\EscapeChar\MacronCode}
1337 \def\Macron{\noexpand\SaveMacron}
1338
1339 % |. IS AN ENCODED \.
1340 \def\OverdotCode{.}
1341 \def\EncodedOverdot{\EscapeChar\OverdotCode}
1342 \def\Overdot{\noexpand\SaveOverdot}
1343
1344 % |u IS AN ENCODED \u
1345 \def\BreveCode{u}
1346 \def\EncodedBreve{\EscapeChar\BreveCode}
1347 \def\Breve{\noexpand\SaveBreve}
1348
1349 % |v IS AN ENCODED \v
1350 \def\CaronCode{v}
1351 \def\EncodedCaron{\EscapeChar\CaronCode}
1352 \def\Caron{\noexpand\SaveCaron}
1353
1354 % |H IS AN ENCODED \H
1355 \def\DoubleAcuteCode{H}
1356 \def\EncodedDoubleAcute{\EscapeChar\DoubleAcuteCode}
1357 \def\DoubleAcute{\noexpand\SaveDoubleAcute}
1358
1359 % |c IS AN ENCODED \c
1360 \def\CedillaCode{c}
1361 \def\EncodedCedilla{\EscapeChar\CedillaCode}
1362 \def\Cedilla{\noexpand\SaveCedilla}
1363
1364 % |d IS AN ENCODED \d
1365 \def\UnderdotCode{d}
1366 \def\EncodedUnderdot{\EscapeChar\UnderdotCode}
1367 \def\Underdot{.}% CANNOT \edef \d
1368
1369 % |t IS AN ENCODED \t
1370 \def\ArchJoinCode{t}
1371 \def\EncodedArchJoin{\EscapeChar\ArchJoinCode}
1372 \def\ArchJoin{.}% CANNOT \edef \t
1373
1374 % |b IS AN ENCODED \b
1375 \def\LineUnderCode{b}
1376 \def\EncodedLineUnder{\EscapeChar\LineUnderCode}
1377 \def\LineUnder{.}% CANNOT \edef \b
1378
1379 % |C IS AN ENCODED \copyright
1380 \def\CopyrightCode{C}
1381 \def\EncodedCopyright{\EscapeChar\CopyrightCode}
1382 \def\Copyright{.}% CANNOT \edef \copyright
1383
1384 % |p IS AN ENCODED \pounds
1385 \def\PoundsCode{p}
1386 \def\EncodedPounds{\EscapeChar\PoundsCode}
1387 \def\Pounds{\SavePounds}
1388
1389 % |[ IS AN ENCODED {
1390 \def\LBCode{[}
1391 \def\EncodedLB{\EscapeChar\LBCode}
1392 \def\UnencodedLB{.}
1393 \def\LB{\EncodedLB}
1394
1395 % |] IS AN ENCODED }
1396 \def\RBCode{]}
1397 \def\EncodedRB{\EscapeChar\RBCode}
1398 \def\UnencodedRB{.}
1399 \def\RB{\EncodedRB}
1400
1401 % |z IS AN ENCODED \dag
1402 \def\DaggerCode{z}
1403 \def\EncodedDagger{\EscapeChar\DaggerCode}
1404 \def\Dagger{.}% CANNOT \edef \dag
1405
1406 % |Z IS AN ENCODED \ddag
1407 \def\DoubleDaggerCode{Z}
1408 \def\EncodedDoubleDagger{\EscapeChar\DoubleDaggerCode}
1409 \def\DoubleDagger{.}% CANNOT \edef \ddag
1410
1411 % |S IS AN ENCODED \S
1412 \def\SectionSymbolCode{S}
1413 \def\EncodedSectionSymbol{\EscapeChar\SectionSymbolCode}
1414 \def\SectionSymbol{\SaveSectionSymbol}
1415
1416 % |P IS AN ENCODED \P
1417 \def\PilcrowCode{P}
1418 \def\EncodedPilcrow{\EscapeChar\PilcrowCode}
1419 \def\Pilcrow{.}% CANNOT \edef \P
1420
1421 % |E IS AN ENCODED \AE
1422 \def\AEscCode{E}
1423 \def\EncodedAEsc{\EscapeChar\AEscCode}
1424 \def\AEsc{\SaveAEsc}
1425
1426 % |e IS AN ENCODED \ae
1427 \def\aescCode{e}
1428 \def\Encodedaesc{\EscapeChar\aescCode}
1429 \def\aesc{\Saveaesc}
1430
1431 % |O IS AN ENCODED \OE
1432 \def\OEthelCode{O}
1433 \def\EncodedOEthel{\EscapeChar\OEthelCode}
1434 \def\OEthel{\SaveOEthel}
1435
1436 % |o IS AN ENCODED \oe
1437 \def\oethelCode{o}
1438 \def\Encodedoethel{\EscapeChar\oethelCode}
1439 \def\oethel{\Saveoethel}
1440
1441 % |A IS AN ENCODED \AA
1442 \def\AngstromCode{A}
1443 \def\EncodedAngstrom{\EscapeChar\AngstromCode}
1444 \def\Angstrom{\SaveAngstrom}
1445
1446 % |a IS AN ENCODED \aa
1447 \def\angstromCode{a}
1448 \def\Encodedangstrom{\EscapeChar\angstromCode}
1449 \def\angstrom{\Saveangstrom}
1450
1451 % |Q IS AN ENCODED \O
1452 \def\SlashedOCode{Q}
1453 \def\EncodedSlashedO{\EscapeChar\SlashedOCode}
1454 \def\SlashedO{\SaveSlashedO}
1455
1456 % |q IS AN ENCODED \o
1457 \def\SlashedoCode{q}
1458 \def\EncodedSlashedo{\EscapeChar\SlashedoCode}
1459 \def\Slashedo{\SaveSlashedo}
1460
1461 % |L IS AN ENCODED \L
1462 \def\BarredLCode{L}
1463 \def\EncodedBarredL{\EscapeChar\BarredLCode}
1464 \def\BarredL{\SaveBarredL}
1465
1466 % |l IS AN ENCODED \l
1467 \def\BarredlCode{l}
1468 \def\EncodedBarredl{\EscapeChar\BarredlCode}
1469 \def\Barredl{\SaveBarredl}
1470
1471 % |s IS AN ENCODED \ss
1472 \def\EszettCode{s}
1473 \def\EncodedEszett{\EscapeChar\EszettCode}
1474 \def\Eszett{\SaveEszett}
1475
1476 \newcounter{@letterindex}
1477 \newcounter{@@letterindex}
1478 \newcounter{@@@letterindex}
1479 \newcounter{@wordindex}
1480 \newcounter{@iargc}
1481 \newcounter{@gobblesize}
1482 \newcounter{@maxrotation}
1483 \newcounter{@stringsize}
1484 \newcounter{@@stringsize}
1485 \newcounter{@@@stringsize}
1486 \newcounter{@revisedstringsize}
1487 \newcounter{@gobbleindex}
1488 \newcounter{@charsfound}
1489 \newcounter{@alph}
1490 \newcounter{@alphaindex}
1491 \newcounter{@capstrigger}
1492 \newcounter{@fromindex}
1493 \newcounter{@toindex}
1494 \newcounter{@previousindex}
1495 \newcounter{@flag}
1496 \newcounter{@matchloc}
1497 \newcounter{@matchend}
1498 \newcounter{@matchsize}
1499 \newcounter{@matchmax}
1500 \newcounter{@skipped}
1501 \newcounter{@lcwords}
1502 % \end{macrocode}
1503 % \begin{macrocode}
1504 %%%%% CONFIGURATION COMMANDS %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1505 % \end{macrocode}
1506
1507 % \begin{macro}{\defaultTreatments}
1508 % This command can be used to restore the default string treatments,
1509 % prior to calling |\substring|. The default treatments leave all
1510 % symbol types intact and unaltered.
1511 % \begin{macrocode}
1512 \newcommand\defaultTreatments{%
1513 \def\EncodingTreatment{v}% <--Set=v to decode special chars (vs. q,e)
1514 \def\AlphaCapsTreatment{1}% <--Set=1 to retain uppercase (vs. 0,2)
1515 \def\AlphaTreatment{1}% <--Set=1 to retain lowercase (vs. 0,2)
1516 \def\PunctuationTreatment{1}% <--Set=1 to retain punctuation (vs. 0)
1517 \def\NumeralTreatment{1}% <--Set=1 to retain numerals (vs. 0)
1518 \def\SymbolTreatment{1}% <--Set=1 to retain special chars (vs. 0)
1519 \def\BlankTreatment{1}% <--Set=1 to retain blanks (vs. 0)
1520 \def\CapitalizeString{0}% <--Set=0 for no special action (vs. 1,2)
1521 \def\SeekBlankSpace{0}% <--Set=0 for no special action (vs. 1,2)
1522 }
1523 \defaultTreatments
1524 % \end{macrocode}
1525 % \end{macro}
1526
1527 % \begin{macro}{\Treatments}
1528 % This command allows the user to specify the desired character class
1529 % treatments, prior to a call to |\substring|. Unfortunately for the
1530 % user, I have specified which character class each symbol belongs to.
1531 % Therefore, it is not easy if the user decides that he wants a cedilla,
1532 % for example, to be treated like an alphabetic character rather than
1533 % a symbol.
1534 % \begin{macrocode}
1535 % QUICK WAY TO SET UP TREATMENTS BY WHICH \@rotate HANDLES VARIOUS
1536 % CHARACTERS
1537 \newcommand\Treatments[6]{%
1538 \def\AlphaCapsTreatment{#1}% <--Set=0 to remove uppercase
1539 % =1 to retain uppercase
1540 % =2 to change UC to lc
1541 \def\AlphaTreatment{#2}% <--Set=0 to remove lowercase
1542 % =1 to retain lowercase
1543 % =2 to change lc to UC
1544 \def\PunctuationTreatment{#3}%<--Set=0 to remove punctuation
1545 % =1 to retain punctuation
1546 \def\NumeralTreatment{#4}% <--Set=0 to remove numerals
1547 % =1 to retain numerals
1548 \def\SymbolTreatment{#5}% <--Set=0 to remove special chars
1549 % =1 to retain special chars
1550 \def\BlankTreatment{#6}% <--Set=0 to remove blanks
1551 % =1 to retain blanks
1552 }
1553 % \end{macrocode}
1554 % \end{macro}
1555
1556 % \begin{macro}{\+}
1557 % This command (|\+|) is used to enact the \stringstrings encoding.
1558 % Key symbols are redefined, and any |\edef| which occurs while this
1559 % command is active will adopt these new definitions.
1560 % \begin{macrocode}
1561 % REENCODE MULTIBYTE SYMBOLS USING THE stringstrings ENCODING METHOD
1562 \newcommand\+{%
1563 \def\${\EncodedDollar}%
1564 \def~{\EncodedBlankSpace}%
1565 \def\^{\EncodedCircumflex}%
1566 \def\~{\EncodedTilde}%
1567 \def\"{\EncodedUmlaut}%
1568 \def\`{\EncodedGrave}%
1569 \def\'{\EncodedAcute}%
1570 \def\={\EncodedMacron}%
1571 \def\.{\EncodedOverdot}%
1572 \def\u{\EncodedBreve}%
1573 \def\v{\EncodedCaron}%
1574 \def\H{\EncodedDoubleAcute}%
1575 \def\c{\EncodedCedilla}%
1576 \def\d{\EncodedUnderdot}%
1577 \def\t{\EncodedArchJoin}%
1578 \def\b{\EncodedLineUnder}%
1579 \def\copyright{\EncodedCopyright}%
1580 \def\pounds{\EncodedPounds}%
1581 \def\{{\EncodedLeftBrace}%
1582 \def\}{\EncodedRightBrace}%
1583 \def\_{\EncodedUnderscore}%
1584 \def\dag{\EncodedDagger}%
1585 \def\ddag{\EncodedDoubleDagger}%
1586 \def\S{\EncodedSectionSymbol}%
1587 \def\P{\EncodedPilcrow}%
1588 \def\AE{\EncodedAEsc}%
1589 \def\ae{\Encodedaesc}%
1590 \def\OE{\EncodedOEthel}%
1591 \def\oe{\Encodedoethel}%
1592 \def\AA{\EncodedAngstrom}%
1593 \def\aa{\Encodedangstrom}%
1594 \def\O{\EncodedSlashedO}%
1595 \def\o{\EncodedSlashedo}%
1596 \def\L{\EncodedBarredL}%
1597 \def\l{\EncodedBarredl}%
1598 \def\ss{\EncodedEszett}%
1599 }
1600 % \end{macrocode}
1601 % \end{macro}
1602
1603 % \begin{macro}{\?}
1604 % The command |\?| reverts the character encodings back to the standard
1605 % \LaTeX{} definitions. The command effectively undoes a previously
1606 % enacted |\+|.
1607 % \begin{macrocode}
1608 % WHEN TASK IS DONE, REVERT ENCODING TO STANDARD ENCODING METHOD
1609 \newcommand\?{%
1610 \let\$\SaveDollar%
1611 \let~\SaveHardspace%
1612 \let\^\SaveCircumflex%
1613 \let\~\SaveTilde%
1614 \let\"\SaveUmlaut%
1615 \let\`\SaveGrave%
1616 \let\'\SaveAcute%
1617 \let\=\SaveMacron%
1618 \let\.\SaveOverdot%
1619 \let\u\SaveBreve%
1620 \let\v\SaveCaron%
1621 \let\H\SaveDoubleAcute%
1622 \let\c\SaveCedilla%
1623 \let\d\SaveUnderdot%
1624 \let\t\SaveArchJoin%
1625 \let\b\SaveLineUnder%
1626 \let\copyright\SaveCopyright%
1627 \let\pounds\SavePounds%
1628 \let\{\SaveLeftBrace%
1629 \let\}\SaveRightBrace%
1630 \let\_\SaveUnderscore%
1631 \let\dag\SaveDagger%
1632 \let\ddag\SaveDoubleDagger%
1633 \let\S\SaveSectionSymbol%
1634 \let\P\SavePilcrow%
1635 \let\AE\SaveAEsc%
1636 \let\ae\Saveaesc%
1637 \let\OE\SaveOEthel%
1638 \let\oe\Saveoethel%
1639 \let\AA\SaveAngstrom%
1640 \let\aa\Saveangstrom%
1641 \let\O\SaveSlashedO%
1642 \let\o\SaveSlashedo%
1643 \let\L\SaveBarredL%
1644 \let\l\SaveBarredl%
1645 \let\ss\SaveEszett%
1646 }
1647 % \end{macrocode}
1648 % \end{macro}
1649
1650 % \begin{macro}{\encodetoken}
1651 % The command |\encodetoken| assigns the supplied token to one of three
1652 % reserved \stringstrings user variables (the optional argument dictates
1653 % which user variable). Once encoded, the supplied token cannot be used
1654 % in the normal way, but only in stringstrings routines, unless and
1655 % until it is decoded.
1656 % \begin{macrocode}
1657 \newcommand\encodetoken[2][1]{%
1658 \if 1#1%
1659 \let\Uvari#2%
1660 \let#2\uvari\else
1661 \if 2#1%
1662 \let\Uvarii#2%
1663 \let#2\uvarii\else
1664 \if 3#1%
1665 \let\Uvariii#2%
1666 \let#2\uvariii%
1667 \fi
1668 \fi
1669 \fi
1670 }
1671 % \end{macrocode}
1672 % \end{macro}
1673
1674 % \begin{macro}{\decodetoken}
1675 % The command |\decodetoken| deassigns the supplied token from the
1676 % reserved \stringstrings user variables (the optional argument dictates
1677 % which user variable), so that the token may be used in the normal way
1678 % again.
1679 % \begin{macrocode}
1680 \newcommand\decodetoken[2][1]{%
1681 \if 1#1%
1682 \let#2\Uvari%
1683 \def\Uvari{Uvari}\else
1684 \if 2#1%
1685 \let#2\Uvarii%
1686 \def\Uvarii{Uvarii}\else
1687 \if 3#1%
1688 \let#2\Uvariii%
1689 \def\Uvariii{Uvariii}%
1690 \fi
1691 \fi
1692 \fi
1693 }
1694 % \end{macrocode}
1695 % \end{macro}
1696
1697 % \begin{macrocode}
1698 %%%%% COMMANDS TO MANIPULATE STRINGS %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1699 % \end{macrocode}
1700
1701 % In the next group of commands, the result is always stored in an
1702 % expandable string, |\thestring|. Expandable means that |\thestring| can
1703 % be put into a subsequent |\edef{}| command. Additionally, the
1704 % optional first argument can be used to cause three actions (verbose,
1705 % encoded, or quiet):
1706 % \begin{enumerate}
1707 % \item [|=v|] |\thestring| is decoded (final result);
1708 % print it immediately (default)
1709 % \item [|=e|] |\thestring| is encoded (intermediate result);
1710 % don't print it
1711 % \item [|=q|] |\thestring| is decoded (final result),
1712 % but don't print it
1713 % \end{enumerate}
1714 % \begin{macro}{\substring}
1715 % The command |\substring| is the brains of this package\ldots
1716 % It is used to acquire a substring from a given string, along with
1717 % performing specified character manipulations along the way.
1718 % Its strategy is fundamental to the \stringstrings
1719 % package: sequentially rotate the 1st character of the
1720 % string to the end of the string, until the desired substring resides
1721 % at end of rotated string. Then, gobble up the leading part of
1722 % string until only the desired substring is left.
1723 % \begin{macrocode}
1724 \newcommand\substring[4][v]{\+%
1725 % \end{macrocode}
1726 % Obtain the string length of the string to be manipulated and store
1727 % it in |@stringsize|.
1728 % \begin{macrocode}
1729 \@getstringlength{#2}{@stringsize}%
1730 % \end{macrocode}
1731 % First,
1732 % |\@decodepointer| is used to convert indirect references like |$|
1733 % and |$-3| into integers.
1734 % \begin{macrocode}
1735 \@decodepointer{#3}%
1736 \setcounter{@fromindex}{\@fromtoindex}%
1737 \@decodepointer{#4}%
1738 \setcounter{@toindex}{\@fromtoindex}%
1739 % \end{macrocode}
1740 % Determine the number of characters to rotate to the end of the string
1741 % and the number of characters to then gobble from it, in order to leave
1742 % the desired substring.
1743 % \begin{macrocode}
1744 \setcounter{@gobblesize}{\value{@stringsize}}%
1745 \ifthenelse{\value{@toindex} > \value{@stringsize}}%
1746 {\setcounter{@maxrotation}{\value{@stringsize}}}%
1747 {\setcounter{@maxrotation}{\value{@toindex}}}%
1748 \addtocounter{@gobblesize}{-\value{@maxrotation}}%
1749 \addtocounter{@gobblesize}{\value{@fromindex}}%
1750 \addtocounter{@gobblesize}{-1}%
1751 % \end{macrocode}
1752 % Prepare for the string rotation by initializing counters, setting the
1753 % targeted string into the working variable, |\rotatingword|, and set
1754 % the encoding treatment specified.
1755 % \begin{macrocode}
1756 \setcounter{@letterindex}{0}%
1757 \edef\rotatingword{#2}%
1758 \def\EncodingTreatment{#1}%
1759 % \end{macrocode}
1760 % If capitalization (first character of string or of each word)
1761 % was specified, the
1762 % trigger for 1st-character capitalization will be set. However,
1763 % the treatments for the alphabetic characters for the remainder of the
1764 % string must be saved and reinstituted after the first character is
1765 % capitalized.
1766 % \begin{macrocode}
1767 \if 0\CapitalizeString%
1768 % DO NOT SET CAPITALIZE TRIGGER FOR FIRST CHARACTER
1769 \setcounter{@capstrigger}{0}%
1770 \else
1771 % SAVE CERTAIN TREATMENTS FOR LATER RESTORATION
1772 \let\SaveAlphaTreatment\AlphaTreatment%
1773 \let\SaveAlphaCapsTreatment\AlphaCapsTreatment%
1774 % SET CAPITALIZE TRIGGER FOR FIRST CHARACTER
1775 \setcounter{@capstrigger}{1}%
1776 \@forcecapson%
1777 \fi
1778 % \end{macrocode}
1779 % The command |\@defineactions| looks at the defined treatments
1780 % and specifies how each of the \stringstrings encoded
1781 % characters should be handled (\ie left alone, removed, modified,
1782 % \etc).
1783 % \begin{macrocode}
1784 \@defineactions%
1785 % \end{macrocode}
1786 % Here begins the primary loop of |\substring| in which characters of
1787 % |\rotatingword| are successively moved (and possibly manipulated)
1788 % from the first character of the string to the last. |@letterindex| is
1789 % the running index defining how many characters have been operated on.
1790 % \begin{macrocode}
1791 \whiledo{\value{@letterindex} < \value{@maxrotation}}{%
1792 \addtocounter{@letterindex}{1}%
1793 % \end{macrocode}
1794 % When |\CapitalizeString| equals 1, only the first character of the
1795 % string is capitalized. When it equals 2, every word in the string
1796 % is capitalized. When equal to 2, this bit of code looks for the
1797 % blankspace that follows the end of a word, and uses it to reset the
1798 % capitalization trigger for the next non-blank character.
1799 % \begin{macrocode}
1800 % IF NEXT CHARACTER BLANK WHILE \CapitalizeString=2,
1801 % SET OR KEEP ALIVE TRIGGER.
1802 \if 2\CapitalizeString%
1803 \isnextbyte[q]{\EncodedBlankSpace}{\rotatingword}%
1804 \if F\theresult\isnextbyte[q]{\BlankSpace}{\rotatingword}\fi%
1805 \if T\theresult%
1806 \if 0\arabic{@capstrigger}%
1807 \@forcecapson%
1808 \@defineactions%
1809 \fi
1810 \setcounter{@capstrigger}{2}%
1811 \fi
1812 \fi
1813 % \end{macrocode}
1814 % Is the next character an encoded symbol? If it is a normal character,
1815 % simply rotate it to the end of the string.
1816 % If it is an encoded symbol however, its
1817 % treatment will depend on whether it will be gobbled away or end up
1818 % in the final substring. If it will be gobbled away, leave it encoded,
1819 % because the gobbling routine knows how to gobble encoded characters.
1820 % If it will end up in the substring, manipulate it according to the
1821 % encoding rules set in |\@defineactions| and rotate it.
1822 % \begin{macrocode}
1823 % CHECK IF NEXT CHARACTER IS A SYMBOL
1824 \isnextbyte[q]{\EscapeChar}{\rotatingword}%
1825 \ifthenelse{\value{@letterindex} < \value{@fromindex}}%
1826 {%
1827 % THIS CHARACTER WILL EVENTUALLY BE GOBBLED
1828 \if T\theresult%
1829 % ROTATE THE ESCAPE CHARACTER, WHICH WILL LEAVE THE SYMBOL ENCODED
1830 % FOR PROPER GOBBLING (ESCAPE CHARACTER DOESN'T COUNT AS A LETTER)
1831 \edef\rotatingword{\@rotate{\rotatingword}}%
1832 \addtocounter{@letterindex}{-1}%
1833 \else
1834 % NORMAL CHARACTER OR SYMBOL CODE... ROTATE IT
1835 \edef\rotatingword{\@rotate{\rotatingword}}%
1836 \fi
1837 }%
1838 {%
1839 % THIS CHARACTER WILL EVENTUALLY MAKE IT INTO SUBSTRING
1840 \if T\theresult%
1841 % ROTATE THE SYMBOL USING DEFINED TREATMENT RULES
1842 \edef\rotatingword{\ESCrotate{\expandafter\@gobble\rotatingword}}%
1843 \else
1844 % NORMAL CHARACTER... ROTATE IT
1845 \edef\rotatingword{\@rotate{\rotatingword}}%
1846 \fi
1847 }%
1848 % \end{macrocode}
1849 % Here, the capitalization trigger persistently tries to turn
1850 % itself off with each loop
1851 % through the string rotation. Only if the earlier code found the
1852 % rotation to be pointing to the blank character(s) between words while
1853 % |\CapitalizeString| equals 2 will the trigger be prevented from
1854 % extinguishing itself.
1855 % \begin{macrocode}
1856 % DECREMENT CAPITALIZATION TRIGGER TOWARDS 0, EVERY TIME THROUGH LOOP
1857 \if 0\arabic{@capstrigger}%
1858 \else
1859 \addtocounter{@capstrigger}{-1}%
1860 \if 0\arabic{@capstrigger}\@relaxcapson\fi
1861 \fi
1862 % \end{macrocode}
1863 % In addition to the standard |\substring| calls in which fixed
1864 % substring limits are specified (which in turn fixes the number of
1865 % character rotations to be executed), some \stringstrings commands
1866 % want the rotations to continue until a blankspace is located.
1867 % This bit of code looks for that blank space, if that was the option
1868 % requested. Once found, the rotation will stop. However, depending
1869 % on the value of |\SeekBlankSpace|, the remainder of the string may
1870 % either be retained or discarded.
1871 % \begin{macrocode}
1872 % IF SOUGHT SPACE IS FOUND, END ROTATION OF STRING
1873 \if 0\SeekBlankSpace\else
1874 \isnextbyte[q]{\EncodedBlankSpace}{\rotatingword}%
1875 \if F\theresult\isnextbyte[q]{\BlankSpace}{\rotatingword}\fi%
1876 \if T\theresult%
1877 \if 1\SeekBlankSpace%
1878 % STOP ROTATION, KEEP REMAINDER OF STRING
1879 \setcounter{@maxrotation}{\value{@letterindex}}%
1880 \else
1881 % STOP ROTATION, THROW AWAY REMAINDER OF STRING
1882 \addtocounter{@gobblesize}{\value{@maxrotation}}%
1883 \setcounter{@maxrotation}{\value{@letterindex}}%
1884 \addtocounter{@gobblesize}{-\value{@maxrotation}}%
1885 \fi
1886 \fi
1887 \fi
1888 }%
1889 % \end{macrocode}
1890 % The loop has ended.\\
1891 % Gobble up the first |@gobblesize| characters (not bytes!)~of the string,
1892 % which should leave the desired substring as the remainder. If the
1893 % mode is verbose, print out the resulting substring.
1894 % \begin{macrocode}
1895 % GOBBLE AWAY THAT PART OF STRING THAT ISN'T PART OF REQUESTED SUBSTRING
1896 \@gobblearg{\rotatingword}{\arabic{@gobblesize}}%
1897 \edef\thestring{\gobbledword}%
1898 \if v#1\thestring\fi%
1899 \?}
1900 % \end{macrocode}
1901 % \end{macro}
1902
1903 % Many of the following commands are self-expanatory. The recipe they
1904 % follow is to use |\Treatments| to specify how different character
1905 % classes are to be manipulated, and then to call upon |\substring| to
1906 % effect the desired manipulation. Treatments are typically
1907 % re-defaulted at the conclusion of the command, which is why the user,
1908 % if desiring special treatments, should specify those treatments
1909 % immediately before a call to |\substring|.
1910 % \begin{macro}{\caseupper}
1911 % \begin{macrocode}
1912 % Convert Lower to Uppercase; retain all symbols, numerals,
1913 % punctuation, and blanks.
1914 \newcommand\caseupper[2][v]{%
1915 \Treatments{1}{2}{1}{1}{1}{1}%
1916 \substring[#1]{#2}{1}{\@MAXSTRINGSIZE}%
1917 \defaultTreatments%
1918 }
1919 % \end{macrocode}
1920 % \end{macro}
1921
1922 % \begin{macro}{\caselower}
1923 % \begin{macrocode}
1924 % Convert Upper to Lowercase; retain all symbols, numerals,
1925 % punctuation, and blanks.
1926 \newcommand\caselower[2][v]{%
1927 \Treatments{2}{1}{1}{1}{1}{1}%
1928 \substring[#1]{#2}{1}{\@MAXSTRINGSIZE}%
1929 \defaultTreatments%
1930 }
1931 % \end{macrocode}
1932 % \end{macro}
1933
1934 % \begin{macro}{\solelyuppercase}
1935 % \begin{macrocode}
1936 % Convert Lower to Uppercase; discard symbols, numerals, and
1937 % punctuation, but keep blanks.
1938 \newcommand\solelyuppercase[2][v]{%
1939 \Treatments{1}{2}{0}{0}{0}{1}%
1940 \substring[#1]{#2}{1}{\@MAXSTRINGSIZE}%
1941 \defaultTreatments%
1942 }
1943 % \end{macrocode}
1944 % \end{macro}
1945
1946 % \begin{macro}{\solelylowercase}
1947 % \begin{macrocode}
1948 % Convert Upper to Lowercase; discard symbols, numerals, and
1949 % punctuation, but keep blanks.
1950 \newcommand\solelylowercase[2][v]{%
1951 \Treatments{2}{1}{0}{0}{0}{1}%
1952 \substring[#1]{#2}{1}{\@MAXSTRINGSIZE}%
1953 \defaultTreatments%
1954 }
1955 % \end{macrocode}
1956 % \end{macro}
1957
1958 % \begin{macro}{\changecase}
1959 % \begin{macrocode}
1960 % Convert Lower to Uppercase & Upper to Lower; retain all symbols, numerals,
1961 % punctuation, and blanks.
1962 \newcommand\changecase[2][v]{%
1963 \Treatments{2}{2}{1}{1}{1}{1}%
1964 \substring[#1]{#2}{1}{\@MAXSTRINGSIZE}%
1965 \defaultTreatments%
1966 }
1967 % \end{macrocode}
1968 % \end{macro}
1969
1970 % \begin{macro}{\noblanks}
1971 % \begin{macrocode}
1972 % Remove blanks; retain all else.
1973 \newcommand\noblanks[2][v]{%
1974 \Treatments{1}{1}{1}{1}{1}{0}%
1975 \substring[#1]{#2}{1}{\@MAXSTRINGSIZE}%
1976 \defaultTreatments%
1977 }
1978 % \end{macrocode}
1979 % \end{macro}
1980
1981 % \begin{macro}{\nosymbolsnumerals}
1982 % \begin{macrocode}
1983 % Retain case; discard symbols & numerals; retain
1984 % punctuation & blanks.
1985 \newcommand\nosymbolsnumerals[2][v]{%
1986 \Treatments{1}{1}{1}{0}{0}{1}%
1987 \substring[#1]{#2}{1}{\@MAXSTRINGSIZE}%
1988 \defaultTreatments%
1989 }
1990 % \end{macrocode}
1991 % \end{macro}
1992
1993 % \begin{macro}{\alphabetic}
1994 % \begin{macrocode}
1995 % Retain case; discard symbols, numerals &
1996 % punctuation; retain blanks.
1997 \newcommand\alphabetic[2][v]{%
1998 \Treatments{1}{1}{0}{0}{0}{1}%
1999 \substring[#1]{#2}{1}{\@MAXSTRINGSIZE}%
2000 \defaultTreatments%
2001 }
2002 % \end{macrocode}
2003 % \end{macro}
2004
2005 % \begin{macro}{\capitalize}
2006 % The command |\CapitalizeString| is not set by |\Treatments|, but
2007 % only in |\capitalize| or in |\capitalizewords|.
2008 % \begin{macrocode}
2009 % Capitalize first character of string,
2010 \newcommand\capitalize[2][v]{%
2011 \defaultTreatments%
2012 \def\CapitalizeString{1}%
2013 \substring[#1]{#2}{1}{\@MAXSTRINGSIZE}%
2014 \def\CapitalizeString{0}%
2015 }
2016 % \end{macrocode}
2017 % \end{macro}
2018
2019 % \begin{macro}{\capitalizewords}
2020 % \begin{macrocode}
2021 % Capitalize first character of each word in string,
2022 \newcommand\capitalizewords[2][v]{%
2023 \defaultTreatments%
2024 \def\CapitalizeString{2}%
2025 \substring[#1]{#2}{1}{\@MAXSTRINGSIZE}%
2026 \def\CapitalizeString{0}%
2027 }
2028 % \end{macrocode}
2029 % \end{macro}
2030
2031 % \begin{macro}{\reversestring}
2032 % Reverses a string from back to front. To do this, a loop is set
2033 % up in which characters are grabbed one at a time from the end of the
2034 % given string, working towards the beginning of the string. The
2035 % grabbed characters are concatenated onto the end of the working
2036 % string, |\@reversedstring|. By the time the loop is complete
2037 % |\@reversedstring| fully represents the reversed string. The result
2038 % is placed into |\thestring|.
2039 % \begin{macrocode}
2040 % REVERSES SEQUENCE OF CHARACTERS IN STRING
2041 \newcommand\reversestring[2][v]{%
2042 \def\@reversedstring{}%
2043 \+\@getstringlength{#2}{@@stringsize}\?%
2044 \setcounter{@@@letterindex}{\the@@stringsize}%
2045 \whiledo{\the@@@letterindex > 0}{%
2046 \if e#1%
2047 \substring[e]{#2}{\the@@@letterindex}{\the@@@letterindex}%
2048 \else
2049 \substring[q]{#2}{\the@@@letterindex}{\the@@@letterindex}%
2050 \fi
2051 \edef\@reversedstring{\@reversedstring\thestring}%
2052 \addtocounter{@@@letterindex}{-1}%
2053 }%
2054 \edef\thestring{\@reversedstring}%
2055 \if v#1\thestring\fi%
2056 }
2057 % \end{macrocode}
2058 % \end{macro}
2059
2060 % \begin{macro}{\convertchar}
2061 % Takes a string, and replaces each occurance of a specified character
2062 % with a replacement string. The only complexity in the logic is that
2063 % a separate replacement algorithm exists depending on whether the
2064 % specified character to be replaced is a normal character or an
2065 % encoded character.
2066 % \begin{macrocode}
2067 % TAKES A STARTING STRING #2 AND SUBSTITUTES A SPECIFIED STRING #4
2068 % FOR EVERY OCCURANCE OF A PARTICULAR GIVEN CHARACTER #3. THE
2069 % CHARACTER TO BE CONVERTED MAY BE EITHER A PLAIN CHARACTER OR
2070 % AN ENCODABLE SYMBOL.
2071 \newcommand\convertchar[4][v]{%
2072 \+%
2073 \edef\encodedstring{#2}%
2074 \edef\encodedfromarg{#3}%
2075 \edef\encodedtoarg{#4}%
2076 \?%
2077 \isnextbyte[q]{\EscapeChar}{\encodedfromarg}%
2078 \if F\theresult%
2079 % PLAIN "FROM" ARGUMENT
2080 \@convertbytetostring[#1]{\encodedstring}{#3}{\encodedtoarg}%
2081 \else
2082 % ENCODABLE "FROM" ARGUMENT
2083 \@convertsymboltostring[#1]{\encodedstring}%
2084 {\expandafter\@gobble\encodedfromarg}{\encodedtoarg}%
2085 \fi
2086 }
2087 % \end{macrocode}
2088 % \end{macro}
2089
2090 % \begin{macro}{\convertword}
2091 % Takes a string, a replaces each occurance of a specified string
2092 % with a replacement string.
2093 % \begin{macrocode}
2094 \newcounter{@@matchloc}
2095 % LIKE \convertchar, EXCEPT FOR WORDS
2096 \newcommand\convertword[4][v]{%
2097 \+\edef\@@teststring{#2}%
2098 \edef\@fromstring{#3}%
2099 \edef\@tostring{#4}\?%
2100 \edef\@@@teststring{\@@teststring}%
2101 \def\@buildfront{}%
2102 \edef\@buildstring{\@@teststring}%
2103 \setcounter{@charsfound}{0}%
2104 \whiledo{\the@charsfound > -1}{%
2105 % \end{macrocode}
2106 % Seek occurance of |\@fromstring| in larger |\@@teststring|
2107 % \begin{macrocode}
2108 \whereisword[q]{\@@teststring}{\@fromstring}%
2109 \setcounter{@matchloc}{\theresult}%
2110 \ifthenelse{\the@matchloc = 0}%
2111 {%
2112 % \end{macrocode}
2113 % Not found. Done.
2114 % \begin{macrocode}
2115 \setcounter{@charsfound}{-1}%
2116 }%
2117 {%
2118 % \end{macrocode}
2119 % Potential matchstring.
2120 % \begin{macrocode}
2121 \addtocounter{@charsfound}{1}%
2122 % \end{macrocode}
2123 % Grab current test string from beginning to point just prior
2124 % to potential match.
2125 % \begin{macrocode}
2126 \addtocounter{@matchloc}{-1}%
2127 \substring[e]{\@@@teststring}{1}{\the@matchloc}%
2128 % \end{macrocode}
2129 % The string |\@buildfront| is the total original string, with
2130 % string substitutions, from character 1 to current potential match.
2131 % \begin{macrocode}
2132 \edef\@buildfront{\@buildfront\thestring}%
2133 % \end{macrocode}
2134 % See if potential matchstring takes us to end-of-string\ldots
2135 % \begin{macrocode}
2136 \addtocounter{@matchloc}{1}%
2137 \addtocounter{@matchloc}{\the@matchsize}%
2138 \ifthenelse{\the@matchloc > \the@@@stringsize}%
2139 {%
2140 % \end{macrocode}
2141 % \ldots if so, then match is last one in string. Tack on replacement
2142 % string to |\@buildfront| to create final string. Exit.
2143 % \begin{macrocode}
2144 \setcounter{@charsfound}{-1}%
2145 \edef\@buildstring{\@buildfront\@tostring}%
2146 }%
2147 {%
2148 % \end{macrocode}
2149 % \ldots if not, redefine current teststring to begin at point following
2150 % the current substitution. Make substitutions to current
2151 % |\@buildstring| and |\@buildfront|. Loop through logic again on new
2152 % teststring.
2153 % \begin{macrocode}
2154 \substring[e]{\@@@teststring}{\the@matchloc}{\@MAXSTRINGSIZE}%
2155 \edef\@@teststring{\thestring}%
2156 \edef\@@@teststring{\@@teststring}%
2157 \edef\@buildstring{\@buildfront\@tostring\@@@teststring}%
2158 \edef\@buildfront{\@buildfront\@tostring}%
2159 }%
2160 }%
2161 }%
2162 \substring[#1]{\@buildstring}{1}{\@MAXSTRINGSIZE}%
2163 }
2164 % \end{macrocode}
2165 % \end{macro}
2166
2167 % \begin{macro}{\resetlcwords}
2168 % Removes all words from designated ``lower-case words'' list. This can
2169 % be useful because large lists of lower-case words can significantly
2170 % slow-down the function of |\capitalizetitle|.
2171 % \begin{macrocode}
2172 \setcounter{@lcwords}{0}
2173 % RESET LOWER-CASE WORD COUNT; START OVER
2174 \newcommand\resetlcwords[0]{%
2175 \setcounter{@lcwords}{0}%
2176 }
2177 % \end{macrocode}
2178 % \end{macro}
2179
2180 % \begin{macro}{\addlcwords}
2181 % Add words to the list of designated ``lower-case words'' which will
2182 % not be capitalized by |\capitalizetitle|. The input should consist of
2183 % space-separated words, which are, in turn, passed on to |\addlcword|.
2184 % \begin{macrocode}
2185 % PROVIDE LIST OF SPACE-SEPARATED WORDS TO REMAIN LOWERCASE IN TITLES
2186 \newcommand\addlcwords[1]{%
2187 \getargs{#1}%
2188 \setcounter{@wordindex}{0}%
2189 \whiledo{\value{@wordindex} < \narg}{%
2190 \addtocounter{@wordindex}{1}%
2191 \addlcword{\csname arg\roman{@wordindex}\endcsname}%
2192 }
2193 }
2194 % \end{macrocode}
2195 % \end{macro}
2196
2197 % \begin{macro}{\addlcword}
2198 % Add a word to the list of designated ``lower-case words'' which will
2199 % not be capitalized by |\capitalizetitle|.
2200 % \begin{macrocode}
2201 % PROVIDE A SINGLE WORD TO REMAIN LOWERCASE IN TITLES
2202 \newcommand\addlcword[1]{%
2203 \addtocounter{@lcwords}{1}%
2204 \expandafter\edef\csname lcword\roman{@lcwords}\endcsname{#1}
2205 }
2206 % \end{macrocode}
2207 % \end{macro}
2208
2209 % \begin{macro}{\capitalizetitle}
2210 % Makes every word of a multi-word input string capitalized, except for
2211 % specifically noted ``lower-case words'' (examples might include
2212 % prepositions, conjunctions, \etc). The first word of the input string
2213 % is capitalized, while lower-case words, previously designated with
2214 % |\addlcword| and |\addlcwords|, are left in lower case.
2215 % \begin{macrocode}
2216 % CAPITALIZE TITLE, EXCEPT FOR DESIGNATED "LOWER-CASE" WORDS
2217 \newcommand\capitalizetitle[2][v]{%
2218 % First, capitalize every word (save in encoded form, not printed)
2219 \capitalizewords[e]{#2}%
2220 % Then lowercase words that shouldn't be capitalized, like articles,
2221 % prepositions, etc. (save in encoded form, not printed)
2222 \setcounter{@wordindex}{0}%
2223 \whiledo{\value{@wordindex} < \value{@lcwords}}{%
2224 \addtocounter{@wordindex}{1}%
2225 \edef\mystring{\thestring}%
2226 \edef\lcword{\csname lcword\roman{@wordindex}\endcsname}%
2227 \capitalize[e]{\lcword}%
2228 \edef\ucword{\thestring}%
2229 \convertword[e]{\mystring}{\ucword~}{\lcword~}%
2230 }
2231 % Finally, recapitalize the first word of the Title, and print it.
2232 \capitalize[#1]{\thestring}%
2233 }
2234 % \end{macrocode}
2235 % \end{macro}
2236
2237 % \begin{macro}{\rotateword}
2238 % Moves first word of given string |#2| to end of string, including
2239 % leading and trailing blank spaces.
2240 % \begin{macrocode}
2241 \newcommand\rotateword[2][v]{%
2242 \+\edef\thestring{#2}\?%
2243 % \end{macrocode}
2244 % Rotate leading blank spaces to end of string
2245 % \begin{macrocode}
2246 \@treatleadingspaces[e]{\thestring}{}%
2247 % \end{macrocode}
2248 % Define end-of-rotate condition for |\substring| as next blank space
2249 % \begin{macrocode}
2250 \def\SeekBlankSpace{1}%
2251 % \end{macrocode}
2252 % Leave rotated characters alone
2253 % \begin{macrocode}
2254 \Treatments{1}{1}{1}{1}{1}{1}%
2255 % \end{macrocode}
2256 % Rotate to the next blank space or the end of string, whichever comes
2257 % first.
2258 % \begin{macrocode}
2259 \substring[e]{\thestring}{1}{\@MAXSTRINGSIZE}%
2260 % \end{macrocode}
2261 % Rotate trailing spaces.
2262 % \begin{macrocode}
2263 \@treatleadingspaces[#1]{\thestring}{}%
2264 \defaultTreatments%
2265 }
2266 % \end{macrocode}
2267 % \end{macro}
2268
2269 % \begin{macro}{\removeword}
2270 % Remove the first word of given string |#2|, including leading and
2271 % trailing spaces. Note that logic is identical to |\rotateword|,
2272 % except that affected spaces and characters are removed instead of
2273 % being rotated.
2274 % \begin{macrocode}
2275 \newcommand\removeword[2][v]{%
2276 \+\edef\thestring{#2}\?%
2277 % \end{macrocode}
2278 % The |{x}| final argument indicates to delete leading spaces.
2279 % \begin{macrocode}
2280 \@treatleadingspaces[e]{\thestring}{x}%
2281 \def\SeekBlankSpace{1}%
2282 % \end{macrocode}
2283 % The Treatments are specified to remove all characters.
2284 % \begin{macrocode}
2285 \Treatments{0}{0}{0}{0}{0}{0}%
2286 \substring[e]{\thestring}{1}{\@MAXSTRINGSIZE}%
2287 % \end{macrocode}
2288 % Trailing spaces are also deleted.
2289 % \begin{macrocode}
2290 \@treatleadingspaces[#1]{\thestring}{x}%
2291 \defaultTreatments%
2292 }
2293 % \end{macrocode}
2294 % \end{macro}
2295
2296 % \begin{macro}{\getnextword}
2297 % A special case of |\getaword|, where word-to-get is specified as
2298 % ``1''.
2299 % \begin{macrocode}
2300 % GETS NEXT WORD FROM STRING #2.
2301 % NOTE: ROTATES BACK TO BEGINNING, AFTER STRING OTHERWISE EXHAUSTED
2302 \newcommand\getnextword[2][v]{%
2303 \getaword[#1]{#2}{1}%
2304 }
2305 % \end{macrocode}
2306 % \end{macro}
2307
2308 % \begin{macro}{\getaword}
2309 % Obtain a specified word number (|#3|) from string |#2|. Logic: rotate
2310 % leading spaces to end of string; then loop |#3|~--~1 times through
2311 % |\rotateword|. Finally, get next word.
2312 % \begin{macrocode}
2313 % GETS WORD #3 FROM STRING #2.
2314 % NOTE: ROTATES BACK TO BEGINNING, AFTER STRING OTHERWISE EXHAUSTED
2315 \newcommand\getaword[3][v]{%
2316 \setcounter{@wordindex}{1}%
2317 \+\edef\thestring{#2}\?%
2318 \@treatleadingspaces[e]{\thestring}{}%
2319 \whiledo{\value{@wordindex} < #3}{%
2320 \rotateword[e]{\thestring}%
2321 \addtocounter{@wordindex}{1}%
2322 }%
2323 \@getnextword[#1]{\thestring}%
2324 }
2325 % \end{macrocode}
2326 % \end{macro}
2327 %
2328 % \begin{macro}{\rotateleadingspaces}
2329 % Rotate leading spaces of string |#2| to the end of string.
2330 % \begin{macrocode}
2331 \newcommand\rotateleadingspaces[2][v]{%
2332 \@treatleadingspaces[#1]{#2}{}%
2333 }
2334 % \end{macrocode}
2335 % \end{macro}
2336
2337 % \begin{macro}{\removeleadingspaces}
2338 % Remove leading spaces from string |#2|.
2339 % \begin{macrocode}
2340 \newcommand\removeleadingspaces[2][v]{%
2341 \@treatleadingspaces[#1]{#2}{x}%
2342 }
2343 % \end{macrocode}
2344 % \end{macro}
2345
2346 % \begin{macro}{\stringencode}
2347 % \begin{macrocode}
2348 % ENCODE STRING; UNLIKE OTHER COMMANDS, DEFAULT IS NO PRINT
2349 \newcommand\stringencode[2][e]{%
2350 \defaultTreatments%
2351 \substring[#1]{#2}{1}{\@MAXSTRINGSIZE}%
2352 }
2353 % \end{macrocode}
2354 % \end{macro}
2355
2356 % \begin{macro}{\stringdecode}
2357 % \begin{macrocode}
2358 % DECODE STRING
2359 \newcommand\stringdecode[2][v]{%
2360 \defaultTreatments%
2361 \substring[#1]{#2}{1}{\@MAXSTRINGSIZE}%
2362 }
2363 % \end{macrocode}
2364 % \end{macro}
2365
2366 % \begin{macro}{\gobblechar}
2367 % Remove first character (not byte!) from string |#2|. Unlike just about
2368 % all other \stringstrings commands, result is retokenized and not
2369 % expanded.
2370 % \begin{macrocode}
2371 % SINGLE-CHARACTER VERSION OF \gobblechars. IN THIS CASE, TWO-BYTE
2372 % ESCAPE SEQUENCES, WHEN ENCOUNTERED, COUNT AS A SINGLE GOBBLE.
2373 \newcommand\gobblechar[2][q]{\+%
2374 \@gobblearg{#2}{1}%
2375 \?\retokenize[#1]{\gobbledword}%
2376 }
2377 % \end{macrocode}
2378 % \end{macro}
2379
2380 % \begin{macro}{\gobblechars}
2381 % Remove first |#3| characters (not bytes!) from string |#2|.
2382 % Unlike just about all other \stringstrings commands, result is
2383 % retokenized and not expanded.
2384 % \begin{macrocode}
2385 % USER CALLABLE VERSION OF \@gobblearg. TURNS ON REENCODING.
2386 % GOBBLE FIRST #3 CHARACTERS FROM STRING #2. TWO-BYTE
2387 % ESCAPE SEQUENCES, WHEN ENCOUNTERED, COUNT AS A SINGLE GOBBLE.
2388 \newcommand\gobblechars[3][q]{\+%
2389 \@gobblearg{#2}{#3}%
2390 \?\retokenize[#1]{\gobbledword}%
2391 }
2392 % \end{macrocode}
2393 % \end{macro}
2394
2395 % \begin{macro}{\retokenize}
2396 % One of the key \stringstrings routines that provides several
2397 % indispensible functions. Its function is to take an encoded string
2398 % |#2| that has been given, and repopulate the string with its \LaTeX{}
2399 % tokens in a |\def| form (not an expanded |\edef| form). It is
2400 % useful if required to operate on a string outside of the
2401 % \stringstrings library routines, following a \stringstrings
2402 % manipulation. It is also useful to display certain tokens which
2403 % cannot be manipulated in expanded form. See
2404 % Table~\ref{tbl:prob} for a list of tokens that will only work when the
2405 % resulting string is retokenized (and not expanded).
2406 %
2407 % Logic: Loop through each character of given string |#2|. Each
2408 % successive character of the string is retokenized as |\inexttoken|,
2409 % |\iinexttoken|, |\iiinexttoken|, |\ivnexttoken|, \etc, respectively.
2410 % Then a series of strings are formed as\\
2411 % \\
2412 % |\def\buildtoken{}|\\
2413 % |\def\buildtokeni{\builtoken\inexttoken}|\\
2414 % |\def\buildtokenii{\builtokeni\iinexttoken}|\\
2415 % |\def\buildtokeniii{\builtokenii\iiinexttoken}|\\
2416 % |\def\buildtokeniv{\builtokeniii\ivnexttoken}|\\
2417 % \\
2418 % The last in the sequence of |\builtoken...| strings (renamed
2419 % |\buildtokenq|) is the retokenized
2420 % version of string |#2|.
2421 % \begin{macrocode}
2422 % CONVERTS ENCODED STRING BACK INTO TOKENIZED FORM (i.e., def'ED).
2423 \newcommand\retokenize[2][q]{\+%
2424 \edef\@svstring{#2}%
2425 \edef\buildtoken{}%
2426 \@getstringlength{#2}{@@stringsize}\?%
2427 \setcounter{@@letterindex}{0}%
2428 \whiledo{\the@@letterindex < \the@@stringsize}{%
2429 \setcounter{@previousindex}{\the@@letterindex}%
2430 \addtocounter{@@letterindex}{1}%
2431 \substring[e]{\@svstring}{\the@@letterindex}{\the@@letterindex}%
2432 \@retokenizechar{\thestring}{\roman{@@letterindex}nexttoken}%
2433 \expandafter\def\csname buildtoken\roman{@@letterindex}%
2434 \expandafter\endcsname\expandafter%
2435 {\csname buildtoken\roman{@previousindex}\expandafter\endcsname%
2436 \csname\roman{@@letterindex}nexttoken\endcsname}%
2437 }%
2438 \expandafter\def\expandafter\buildtokenq\expandafter{%
2439 \csname buildtoken\roman{@@letterindex}\endcsname}%
2440 \def\thestring{\buildtokenq}%
2441 \if v#1\thestring\fi
2442 }
2443 % \end{macrocode}
2444 % \end{macro}
2445
2446 % \begin{macrocode}
2447 % %%%%% COMMANDS TO EXTRACT STRING INFORMATION %%%%%%%%%%%%%%%%%%%%%%%%%%
2448 % \end{macrocode}
2449
2450 % The following group of commands extract information about a string,
2451 % and store the result in a string called |\theresult|. Since the
2452 % result is not a substring, a \textit{mode} of |[e]| carries no
2453 % meaning. Only |[v]| and |[q]| modes apply here.
2454 % \begin{macro}{\stringlength}
2455 % Returns the length of the given string in \textit{characters}, not
2456 % \textit{bytes}.
2457 % \begin{macrocode}
2458 % USER CALLABLE VERSION of \@getstringlength:
2459 % GET'S STRING LENGTH OF [#2], PUTS RESULT IN \theresult. PRINTS RESULT
2460 % UNLESS IN QUIET [q] MODE.
2461 \newcommand\stringlength[2][v]{\+%
2462 \@getstringlength{#2}{@@stringsize}%
2463 \edef\theresult{\arabic{@@stringsize}}%
2464 \if v#1\theresult\fi%
2465 \?}
2466 % \end{macrocode}
2467 % \end{macro}
2468
2469 % \begin{macro}{\findchars}
2470 % Find number of occurances of character |#3| in string |#2|.
2471 % \begin{macrocode}
2472 % CHECKS TO SEE IF THE CHARACTER [#3] APPEARS ANYWHERE IN STRING [#2].
2473 % THE NUMBER OF OCCURANCES IS PRINTED OUT, EXCEPT WHEN [#1]=q, QUIET
2474 % MODE. RESULT IS ALSO STORED IN \theresult . TO FIND SPACES, ARG3
2475 % SHOULD BE SET TO {~}, NOT { }.
2476 \newcommand\findchars[3][v]{\+%
2477 \@getstringlength{#2}{@@stringsize}%
2478 \setcounter{@charsfound}{0}%
2479 \setcounter{@@letterindex}{0}%
2480 % \end{macrocode}
2481 % Loop through each character of |#2|.
2482 % \begin{macrocode}
2483 \whiledo{\value{@@letterindex} < \value{@@stringsize}}{%
2484 \addtocounter{@@letterindex}{1}%
2485 % \end{macrocode}
2486 % Test if the |@@letterindex| character of string |#2| equals |#3|.
2487 % If so, add to tally.
2488 % \begin{macrocode}
2489 \testmatchingchar{#2}{\arabic{@@letterindex}}{#3}%
2490 \ifmatchingchar\addtocounter{@charsfound}{1}\fi
2491 }%
2492 \edef\theresult{\arabic{@charsfound}}%
2493 \if q#1\else\theresult\fi%
2494 \?}
2495 % \end{macrocode}
2496 % \end{macro}
2497
2498 % \begin{macro}{\whereischar}
2499 % Similar to |\findchars|, but instead finds first occurance of match
2500 % character |#3| within |#2| and returns its location within |#2|.
2501 % \begin{macrocode}
2502 % CHECKS TO FIND LOCATION OF FIRST OCCURANCE OF [#3] IN STRING [#2].
2503 % THE LOCATION IS PRINTED OUT, EXCEPT WHEN [#1]=q, QUIET
2504 % MODE. RESULT IS ALSO STORED IN \theresult . TO FIND SPACES, ARG3
2505 % SHOULD BE SET TO {~}, NOT { }.
2506 \newcommand\whereischar[3][v]{\+%
2507 \@getstringlength{#2}{@@stringsize}%
2508 \edef\@theresult{0}%
2509 \setcounter{@@letterindex}{0}%
2510 % \end{macrocode}
2511 % Loop through characters of |#2| sequentially.
2512 % \begin{macrocode}
2513 \whiledo{\value{@@letterindex} < \value{@@stringsize}}{%
2514 \addtocounter{@@letterindex}{1}%
2515 % \end{macrocode}
2516 % Look for match. If found, save character-location index,
2517 % and reset loop index to break from loop.
2518 % \begin{macrocode}
2519 \testmatchingchar{#2}{\arabic{@@letterindex}}{#3}%
2520 \ifmatchingchar%
2521 \edef\@theresult{\the@@letterindex}%
2522 \setcounter{@@letterindex}{\the@@stringsize}%
2523 \fi
2524 }%
2525 \edef\theresult{\@theresult}%
2526 \if q#1\else\theresult\fi%
2527 \?}
2528 % \end{macrocode}
2529 % \end{macro}
2530
2531 % \begin{macro}{\whereisword}
2532 % Finds location of specified word (|#3|) in string |#2|.
2533 % \begin{macrocode}
2534 % LIKE \whereischar, EXCEPT FOR WORDS
2535 \newcommand\whereisword[3][v]{\+%
2536 \setcounter{@skipped}{0}%
2537 % \end{macrocode}
2538 % |\@@@@teststring| initially contains |#2|. As false alarms are
2539 % located, the string will be redefined to lop off initial characters
2540 % of string.
2541 % \begin{macrocode}
2542 \edef\@@@@teststring{#2}%
2543 \edef\@matchstring{#3}%
2544 \@getstringlength{#2}{@@stringsize}%
2545 \setcounter{@@@stringsize}{\value{@@stringsize}}%
2546 \@getstringlength{#3}{@matchsize}%
2547 \setcounter{@matchmax}{\the@@stringsize}%
2548 \addtocounter{@matchmax}{-\the@matchsize}%
2549 \addtocounter{@matchmax}{1}%
2550 \setcounter{@flag}{0}%
2551 % \end{macrocode}
2552 % Define |\matchchar| as the first character of the match string (|#3|).
2553 % \begin{macrocode}
2554 \substring[e]{#3}{1}{1}%
2555 \edef\matchchar{\thestring}%
2556 \whiledo{\the@flag = 0}{%
2557 % \end{macrocode}
2558 % Look for first character of match string within |\@@@@teststring|.
2559 % \begin{macrocode}
2560 \whereischar[q]{\@@@@teststring}{\matchchar}%
2561 \setcounter{@matchloc}{\theresult}%
2562 \ifthenelse{\equal{0}{\value{@matchloc}}}%
2563 % \end{macrocode}
2564 % If none found, we are done.
2565 % \begin{macrocode}
2566 {%
2567 \setcounter{@flag}{1}%
2568 }%
2569 % \end{macrocode}
2570 % If |\matchchar| is found, must determine if it is the beginning
2571 % of the match string, or just an extraneous match (\ie false alarm).
2572 % Extract substring
2573 % of |\@@@@teststring|, of a size equal to the match string.
2574 % Compare this extracted string with the match string.
2575 % \begin{macrocode}
2576 {%
2577 \setcounter{@matchend}{\theresult}%
2578 \addtocounter{@matchend}{\value{@matchsize}}%
2579 \addtocounter{@matchend}{-1}%
2580 \substring[e]{\@@@@teststring}{\the@matchloc}{\the@matchend}%
2581 \ifthenelse{\equal{\thestring}{\@matchstring}}%
2582 % \end{macrocode}
2583 % Found a match! Save the match location
2584 % \begin{macrocode}
2585 {%
2586 \setcounter{@flag}{1}%
2587 \addtocounter{@matchloc}{\the@skipped}%
2588 \edef\theresult{\the@matchloc}%
2589 }%
2590 % \end{macrocode}
2591 % False alarm. Determine if lopping off the leading characters of
2592 % |\@@@@teststring| (to discard the false-alarm occurance) is feasible.
2593 % If lopping would take one past the end of the string,
2594 % then no match is possible. If lopping permissible, redefine the
2595 % string |\@@@@teststring|, keeping track of the total number of
2596 % lopped-off characters in the counter |@skipped|.
2597 % \begin{macrocode}
2598 {%
2599 \addtocounter{@skipped}{\the@matchloc}%
2600 \addtocounter{@matchloc}{1}%
2601 \ifthenelse{\value{@matchloc} > \value{@matchmax}}%
2602 {%
2603 \setcounter{@flag}{1}%
2604 \edef\theresult{0}%
2605 }%
2606 {%
2607 \substring[e]{\@@@@teststring}{\the@matchloc}{\@MAXSTRINGSIZE}%
2608 \edef\@@@@teststring{\thestring}%
2609 }%
2610 }%
2611 }%
2612 }%
2613 \if q#1\else\theresult\fi%
2614 \?}
2615 % \end{macrocode}
2616 % \end{macro}
2617
2618 % \begin{macro}{\findwords}
2619 % Finds the number of occurances of a word within the provided string
2620 % \begin{macrocode}
2621 % LIKE \findchar, EXCEPT FOR WORDS
2622 \newcommand\findwords[3][v]{%
2623 \+\edef\@@teststring{#2}\?%
2624 \edef\@@@teststring{\@@teststring}%
2625 \setcounter{@charsfound}{0}%
2626 \whiledo{\the@charsfound > -1}{%
2627 % \end{macrocode}
2628 % Seek occurance of |#3| in the string to be tested
2629 % \begin{macrocode}
2630 \whereisword[q]{\@@teststring}{#3}%
2631 \setcounter{@matchloc}{\theresult}%
2632 \ifthenelse{\the@matchloc = 0}%
2633 {%
2634 % \end{macrocode}
2635 % None found. Break from loop.
2636 % \begin{macrocode}
2637 \edef\theresult{\the@charsfound}%
2638 \setcounter{@charsfound}{-1}%
2639 }%
2640 {%
2641 % \end{macrocode}
2642 % Found. Increment count.
2643 % \begin{macrocode}
2644 \addtocounter{@charsfound}{1}%
2645 \addtocounter{@matchloc}{\the@matchsize}%
2646 \ifthenelse{\the@matchloc > \the@@stringsize}%
2647 {%
2648 % \end{macrocode}
2649 % This "find" takes us to the end-of-string. Break from loop now.
2650 % \begin{macrocode}
2651 \edef\theresult{\the@charsfound}%
2652 \setcounter{@charsfound}{-1}%
2653 }%
2654 {%
2655 % \end{macrocode}
2656 % More string to search. Lop off what has been searched from string to
2657 % be tested, and re-loop for next search.
2658 % \begin{macrocode}
2659 \substring[e]{\@@@teststring}{\the@matchloc}{\@MAXSTRINGSIZE}%
2660 \edef\@@teststring{\thestring}%
2661 \edef\@@@teststring{\@@teststring}%
2662 }%
2663 }%
2664 }%
2665 \if q#1\else\theresult\fi%
2666 }
2667 % \end{macrocode}
2668 % \end{macro}
2669
2670 % \begin{macro}{\wordcount}
2671 % Counts words (space-separated text) in a string. Simply removes one
2672 % word at a time, counting the words as it goes. With each removal,
2673 % checks for non-zero string size remaining.
2674 % \begin{macrocode}
2675 % WORD COUNT
2676 \newcommand\wordcount[2][v]{\+%
2677 \edef\@argv{#2}
2678 \@getstringlength{\@argv}{@stringsize}
2679 \setcounter{@iargc}{0}
2680 \whiledo{\value{@stringsize} > 0}{%
2681 \addtocounter{@iargc}{1}%
2682 \removeword[e]{\@argv}%
2683 \edef\@argv{\thestring}%
2684 \@getstringlength{\@argv}{@stringsize}%
2685 }
2686 \edef\theresult{\arabic{@iargc}}%
2687 \if v#1\theresult\fi%
2688 \?}
2689 % \end{macrocode}
2690 % \end{macro}
2691
2692 % \begin{macro}{\getargs}
2693 % Parse a string of arguments in Unix-like manner. Define |\argv| as |#2|.
2694 % Grabs leading word from |\argv| and puts it in |\argi|. Increment
2695 % argument count; remove leading word from |\argv|. Repeat this process,
2696 % with each new argument being placed in |\argii|, |\argiii|, |\argiv|,
2697 % \etc~ Continue until size of |\argv| is exhausted.
2698 % \begin{macrocode}
2699 % OBTAINS ARGUMENTS (WORDS) IN #1 ALA UNIX getarg COMMAND
2700 % narg CONTAINS NUMBER OF ARGUMENTS. ARGUMENTS CONTAINED IN
2701 % argi, argii, argiii, argiv, ETC.
2702 % v mode disabled
2703 \newcommand\getargs[2][q]{\+%
2704 \if v#1\def\@mode{q}\else\def\@mode{#1}\fi%
2705 \edef\@argv{#2}%
2706 \@getstringlength{\@argv}{@stringsize}%
2707 \setcounter{@iargc}{0}%
2708 \whiledo{\value{@stringsize} > 0}{%
2709 \addtocounter{@iargc}{1}%
2710 \getaword[\@mode]{\@argv}{1}%
2711 \expandafter\edef\csname arg\roman{@iargc}\endcsname{\thestring}%
2712 \removeword[e]{\@argv}%
2713 \edef\@argv{\thestring}%
2714 \@getstringlength{\@argv}{@stringsize}%
2715 }%
2716 \edef\narg{\arabic{@iargc}}%
2717 \?}
2718 % \end{macrocode}
2719 % \end{macro}
2720
2721 % \begin{macrocode}
2722 %%%%% COMMANDS TO TEST STRINGS %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2723 % \end{macrocode}
2724
2725 % The following group of commands test for various alphanumeric
2726 % string conditions.
2727 % \begin{macro}{\isnextbyte}
2728 % This routine performs a simple test to determine if the first byte of
2729 % string |#3| matches the byte given by |#2|. The only problem is that
2730 % the test can produce a false negative if the first byte of the test
2731 % string equals the match byte and the second byte of the test string
2732 % equals the |SignalChar| (defined below).
2733 %
2734 % To resolve this possibility, the test is performed twice with two
2735 % different values for |\SignalChar|, only one of which can produce
2736 % a false negative for a given test string. If the two results match,
2737 % then that result gives the correct answer to the question of whether
2738 % the first byte of |#3| equals |#2|. If, however, the two results fail
2739 % to match, then one can assume that one of the results is a false
2740 % negative, and so a ``true'' condition results.
2741 % \begin{macrocode}
2742 % \end{macrocode}
2743 % The following two ``signal characters,'' used for the two tests,
2744 % can be any two distinct characters. They are used solely
2745 % by |\isnextbyte|.
2746 % \begin{macrocode}
2747 \def\PrimarySignalChar{@}
2748 \def\SecondarySignalChar{`}
2749
2750 % \isnextbyte NEEDS TO OPERATE IN RAW (SINGLE BYTE) MODE SO AS TO
2751 % PERFORM TESTS FOR PRESENCE OF \EscapeChar
2752 % \end{macrocode}
2753 % Incidentally,
2754 % |\isnextbyte| can and is used by \stringstrings to detect
2755 % multi-byte characters in a manner which may also be employed by the
2756 % user. To do this:
2757 % First, the string to be tested should be encoded. Then, |\isnextbyte|
2758 % may be used to check for |\EscapeChar| which is how every multi-byte
2759 % character will begin its encoding by the \stringstrings package.
2760 % If |\EscapeChar| is detected as the next character, then the string to
2761 % test may have its leading byte gobbled and the next character (called
2762 % the Escape Code) may be tested, and compared against the known
2763 % \stringstrings escape codes. The combination of
2764 % Escape-Character/Escape-Code is how all multi-byte characters are
2765 % encoded by the \stringstrings package.
2766 % \begin{macrocode}
2767 \newcommand\isnextbyte[3][v]{%
2768 % \end{macrocode}
2769 % Here's the first test\ldots
2770 % \begin{macrocode}
2771 \let\SignalChar\PrimarySignalChar%
2772 \edef\@x{\if #2#3\else\SignalChar\fi}%
2773 \edef\@x{\if \SignalChar\@x F\else T\fi}%
2774 % \end{macrocode}
2775 % \ldots and the second
2776 % \begin{macrocode}
2777 \let\SignalChar\SecondarySignalChar%
2778 \edef\@y{\if #2#3\else\SignalChar\fi}%
2779 \edef\@y{\if \SignalChar\@y F\else T\fi}%
2780 % \end{macrocode}
2781 % If the two tests produced the same result, then a comparison of |\@x\@y|
2782 % and |\@y\@x| will show it.
2783 % \begin{macrocode}
2784 % BECAUSE THE METHOD ONLY PRODUCES FALSE NEGATIVES, IF RESULTS DON'T
2785 % AGREE FROM USING TWO DIFFERENT SIGNAL CHARACTERS, RESULT MUST BE TRUE.
2786 \ifthenelse{\equal{\@x\@y}{\@y\@x}}
2787 {\edef\theresult{\@x}}%
2788 % CORRECT THE FALSE NEGATIVE
2789 {\edef\theresult{T}}%
2790 \if q#1\else\theresult\fi
2791 }
2792 % \end{macrocode}
2793 % \end{macro}
2794
2795 % \begin{macro}{\testmatchingchar}
2796 % This routine checks for a specified match-character within a target
2797 % string. Unlike |\isnextbyte|, this
2798 % routine checks for characters (single- or multi-byte) and not just
2799 % individual bytes. Additionally, rather than testing the
2800 % match-character against the first byte of the test-string, the user
2801 % specifies (through |#2|) which byte of the test-string should be
2802 % compared to the match-character.
2803 %
2804 % This routine is not as efficient as |\isnextbyte|, but much more
2805 % versatile.
2806 % \begin{macrocode}
2807 % CHECKS TO SEE IF [#2]'th CHARACTER IN STRING [#1] EQUALS [#3]
2808 % RESULT STORED IN BOOLEAN \ifmatchingchar
2809 \newif\ifmatchingchar
2810 \newcommand\testmatchingchar[3]{%
2811 \setbox0=\hbox{%
2812 % \end{macrocode}
2813 % Extract desired character from test string
2814 % \begin{macrocode}
2815 \substring[e]{#1}{#2}{#2}\+%
2816 % \end{macrocode}
2817 % Determine if the match-character is a multi-byte symbol.
2818 % \begin{macrocode}
2819 \isnextbyte[q]{\EscapeChar}{#3}%
2820 \if T\theresult%
2821 % \end{macrocode}
2822 % Is the tested character also a multi-byte symbol?
2823 % \begin{macrocode}
2824 \isnextbyte[q]{\EscapeChar}{\thestring}%
2825 \if T\theresult%
2826 % \end{macrocode}
2827 % Yes it is\ldots Therefore, compare codes following the escape character
2828 % \begin{macrocode}
2829 \edef\@testcode{\expandafter\@DiscardNextChar\expandafter{#3}}%
2830 \edef\@teststring{\@DiscardNextChar{\thestring}}%
2831 \if \@teststring\@testcode\matchingchartrue\else\matchingcharfalse\fi
2832 \else
2833 % \end{macrocode}
2834 % No, we are comparing a normal character against a multi-byte symbol
2835 % (apples and oranges), a false comparison.
2836 % \begin{macrocode}
2837 \global\matchingcharfalse%
2838 \fi
2839 \else
2840 % \end{macrocode}
2841 % No, we are comparing two normal one-byte characters, not a mult-byte
2842 % character.
2843 % \begin{macrocode}
2844 \if \thestring#3\global\matchingchartrue\else\global\matchingcharfalse\fi
2845 \fi}%
2846 \?}
2847 % \end{macrocode}
2848 % \end{macro}
2849
2850 % \begin{macro}{\testcapitalized}
2851 % This routine checks to see if first character of string is
2852 % capitalized. The only quirk is that the routine must ascertain
2853 % whether that character is a single-byte character or a multi-byte
2854 % character.
2855 % \begin{macrocode}
2856 \newif\ifcapitalized
2857 \newcommand\testcapitalized[1]{\+%
2858 \setbox0=\hbox{%
2859 \isnextbyte[q]{\EscapeChar}{#1}%
2860 \if T\theresult%
2861 \def\EncodingTreatment{e}%
2862 \edef\rotatingword{#1}%
2863 % \end{macrocode}
2864 % Rotate the first [multi-byte] character of the string to the end
2865 % of the string, lowering its case. Store as |\@stringA|.
2866 % \begin{macrocode}
2867 \def\AlphaCapsTreatment{2}%
2868 \@defineactions%
2869 \edef\@stringA{\ESCrotate{\expandafter\@gobble\rotatingword}}%
2870 % \end{macrocode}
2871 % Rotate the first [multi-byte] character of the string to the end
2872 % of the string, retaining its case. Store as |\@stringB|.
2873 % \begin{macrocode}
2874 \def\AlphaCapsTreatment{1}%
2875 \@defineactions%
2876 \edef\@stringB{\ESCrotate{\expandafter\@gobble\rotatingword}}%
2877 \else
2878 % \end{macrocode}
2879 % \ldots or, if the first character is a normal one-byte character\ldots
2880 % Rotate the first [normal] character of the string to the end
2881 % of the string, lowering its case. Store as |\@stringA|.
2882 % \begin{macrocode}
2883 \def\AlphaCapsTreatment{2}%
2884 \edef\@stringA{\@rotate{#1}}%
2885 % \end{macrocode}
2886 % Rotate the first [normal] character of the string to the end
2887 % of the string, retaining its case. Store as |\@stringB|.
2888 % \begin{macrocode}
2889 \def\AlphaCapsTreatment{1}%
2890 \edef\@stringB{\@rotate{#1}}%
2891 \fi
2892 % \end{macrocode}
2893 % Compare strings A and B, to see if changing the case of first letter
2894 % altered the string
2895 % \begin{macrocode}
2896 \ifthenelse{\equal{\@stringA}{\@stringB}}%
2897 {\global\capitalizedfalse}{\global\capitalizedtrue}}\?%
2898 \defaultTreatments%
2899 }
2900 % \end{macrocode}
2901 % \end{macro}
2902
2903 % \begin{macro}{\testuncapitalized}
2904 % This routine is the complement of |\testcapitalized|. The only
2905 % difference is that the |\@stringA| has its case made upper for the
2906 % comparison, instead of lowered.
2907 % \begin{macrocode}
2908 \newif\ifuncapitalized
2909 \newcommand\testuncapitalized[1]{\+%
2910 \setbox0=\hbox{%
2911 \isnextbyte[q]{\EscapeChar}{#1}%
2912 \if T\theresult%
2913 \def\EncodingTreatment{e}%
2914 \edef\rotatingword{#1}%
2915 \def\AlphaTreatment{2}%
2916 \@defineactions%
2917 \edef\@stringA{\ESCrotate{\expandafter\@gobble\rotatingword}}%
2918 \def\AlphaTreatment{1}%
2919 \@defineactions%
2920 \edef\@stringB{\ESCrotate{\expandafter\@gobble\rotatingword}}%
2921 \else
2922 \def\AlphaTreatment{2}%
2923 \edef\@stringA{\@rotate{#1}}%
2924 \def\AlphaTreatment{1}%
2925 \edef\@stringB{\@rotate{#1}}%
2926 \fi
2927 \ifthenelse{\equal{\@stringA}{\@stringB}}%
2928 {\global\uncapitalizedfalse}{\global\uncapitalizedtrue}}\?%
2929 \defaultTreatments%
2930 }
2931 % \end{macrocode}
2932 % \end{macro}
2933
2934 % \begin{macro}{\testleadingalpha}
2935 % Test if the leading character of the string is alphabetic. This is
2936 % simply accomplished by checking whether the string is either
2937 % capitalized or uncapitalized. If non-alphabetic, it will show
2938 % up as false for both those tests.
2939 % \begin{macrocode}
2940 \newif\ifleadingalpha
2941 \newcommand\testleadingalpha[1]{%
2942 \testcapitalized{#1}%
2943 \ifcapitalized
2944 \leadingalphatrue%
2945 \else
2946 \testuncapitalized{#1}%
2947 \ifuncapitalized
2948 \leadingalphatrue%
2949 \else
2950 \leadingalphafalse%
2951 \fi
2952 \fi
2953 }
2954 % \end{macrocode}
2955 % \end{macro}
2956
2957 % \begin{macro}{\testuppercase}
2958 % Checks to see if all alphabetic characters in a string are uppercase.
2959 % Non-alphabetic characters don't affect the result, unless the string
2960 % is composed solely of nonalphabetic characters, in which case the test
2961 % results is false.
2962 % \begin{macrocode}
2963 \newif\ifuppercase
2964 \newcommand\testuppercase[1]{%
2965 \setbox0=\hbox{%
2966 % \end{macrocode}
2967 % Strip all non-alphabetic characters. Save as |\@stringA|.
2968 % \begin{macrocode}
2969 \Treatments{1}{1}{0}{0}{0}{0}%
2970 \substring[e]{#1}{1}{\@MAXSTRINGSIZE}%
2971 \edef\@stringA{\thestring}%
2972 % \end{macrocode}
2973 % Lower the case of all uppercase characters in |\@stringA|. Save as
2974 % |\@stringB|. Compare these two strings.
2975 % \begin{macrocode}
2976 \def\AlphaTreatment{2}%
2977 \substring[e]{#1}{1}{\@MAXSTRINGSIZE}%
2978 \edef\@stringB{\thestring}%
2979 \ifthenelse{\equal{\@stringA}{\@stringB}}%
2980 {%
2981 % \end{macrocode}
2982 % If the strings are equal, then all the alphabetic characters in the
2983 % original string were uppercase. Need only check to make sure at
2984 % least one alphabetic character was present in the original string.
2985 % \begin{macrocode}
2986 \@getstringlength{\@stringA}{@stringsize}%
2987 \ifthenelse{\value{@stringsize} = 0}%
2988 {\global\uppercasefalse}{\global\uppercasetrue}%
2989 }%
2990 % \end{macrocode}
2991 % If strings are not equal, then the alphabetic characters of the
2992 % original string were not all uppercase. Test false.
2993 % \begin{macrocode}
2994 {\global\uppercasefalse}}%
2995 \defaultTreatments%
2996 }
2997 % \end{macrocode}
2998 % \end{macro}
2999
3000 % \begin{macro}{\ifsolelyuppercase}
3001 % Compare the original string to one made solely uppercase. If they are
3002 % equal (and not composed solely of blankspaces), then the original
3003 % string was solely uppercase to begin with.
3004 % \begin{macrocode}
3005 \newif\ifsolelyuppercase
3006 \newcommand\testsolelyuppercase[1]{%
3007 \setbox0=\hbox{%
3008 \stringencode{#1}%
3009 \edef\@stringA{\thestring}%
3010 \solelyuppercase[e]{#1}%
3011 \edef\@stringB{\thestring}%
3012 \ifthenelse{\equal{\@stringA}{\@stringB}}%
3013 {%
3014 \noblanks[q]{\@stringA}%
3015 \@getstringlength{\thestring}{@stringsize}%
3016 \ifthenelse{\value{@stringsize} = 0}%
3017 {\global\solelyuppercasefalse}{\global\solelyuppercasetrue}%
3018 }%
3019 {\global\solelyuppercasefalse}}%
3020 \defaultTreatments%
3021 }
3022 % \end{macrocode}
3023 % \end{macro}
3024
3025 % \begin{macro}{\testlowercase}
3026 % This routine is the complement to |\testuppercase|, with corresponding
3027 % logic.
3028 % \begin{macrocode}
3029 \newif\iflowercase
3030 \newcommand\testlowercase[1]{%
3031 \setbox0=\hbox{%
3032 \Treatments{1}{1}{0}{0}{0}{0}%
3033 \substring[e]{#1}{1}{\@MAXSTRINGSIZE}%
3034 \edef\@stringA{\thestring}%
3035 \def\AlphaCapsTreatment{2}%
3036 \substring[e]{#1}{1}{\@MAXSTRINGSIZE}%
3037 \edef\@stringB{\thestring}%
3038 \ifthenelse{\equal{\@stringA}{\@stringB}}%
3039 {%
3040 \@getstringlength{\@stringA}{@stringsize}%
3041 \ifnum\value{@stringsize}= 0\relax%
3042 \global\lowercasefalse\else\global\lowercasetrue\fi%
3043 }%
3044 {\global\lowercasefalse}}%
3045 \defaultTreatments%
3046 }
3047 % \end{macrocode}
3048 % \end{macro}
3049
3050 % \begin{macro}{\testsolelylowercase}
3051 % This routine is the complement to |\testsolelyuppercase|, with
3052 % corresponding logic.
3053 % \begin{macrocode}
3054 \newif\ifsolelylowercase
3055 \newcommand\testsolelylowercase[1]{%
3056 \setbox0=\hbox{%
3057 \stringencode{#1}%
3058 \edef\@stringA{\thestring}%
3059 \solelylowercase[e]{#1}%
3060 \edef\@stringB{\thestring}%
3061 \ifthenelse{\equal{\@stringA}{\@stringB}}%
3062 {%
3063 \noblanks[q]{\@stringA}%
3064 \@getstringlength{\thestring}{@stringsize}%
3065 \ifthenelse{\value{@stringsize} = 0}%
3066 {\global\solelylowercasefalse}{\global\solelylowercasetrue}%
3067 }%
3068 {\global\solelylowercasefalse}}%
3069 \defaultTreatments%
3070 }
3071 % \end{macrocode}
3072 % \end{macro}
3073
3074 % \begin{macro}{\testalphabetic}
3075 % Comparable to |\testsolelyuppercase| and
3076 % |\testsolelylowercase| in its logic, this routine tests whether
3077 % the string is purely alphabetic or not.
3078 % \begin{macrocode}
3079 \newif\ifalphabetic
3080 \newcommand\testalphabetic[1]{%
3081 \setbox0=\hbox{%
3082 \stringencode{#1}%
3083 \edef\@stringA{\thestring}%
3084 \alphabetic[e]{#1}%
3085 \edef\@stringB{\thestring}%
3086 \ifthenelse{\equal{\@stringA}{\@stringB}}%
3087 {%
3088 \noblanks[q]{\@stringA}%
3089 \@getstringlength{\thestring}{@stringsize}%
3090 \ifthenelse{\value{@stringsize} = 0}%
3091 {\global\alphabeticfalse}{\global\alphabetictrue}%
3092 }%
3093 {\global\alphabeticfalse}}%
3094 \defaultTreatments%
3095 }
3096 % \end{macrocode}
3097 % \end{macro}
3098
3099 % \begin{macrocode}
3100 %
3101 %%%%% SUPPORT ROUTINES %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3102 %
3103 % \end{macrocode}
3104 % The following routines support the execution of the \stringstrings
3105 % package.
3106
3107 % \begin{macro}{\ESCrotate}
3108 % After the escape character has been ascertained as the next character,
3109 % this routine operates on the subsequent escape code to rotate the
3110 % symbol to end of string, in the fashion of macro |\@rotate|.
3111 % \begin{macrocode}
3112 \newcommand\ESCrotate[1]{%
3113 \if\UvariCode#1\@uvariaction\else
3114 \if\UvariiCode#1\@uvariiaction\else
3115 \if\UvariiiCode#1\@uvariiiaction\else
3116 \if\@fromcode#1\@tostring\else
3117 \if\PipeCode#1\@pipeaction\else
3118 \if\DollarCode#1\@dollaraction\else
3119 \if\CaratCode#1\@carataction\else
3120 \if\CircumflexCode#1\@circumflexaction\else
3121 \if\TildeCode#1\@tildeaction\else
3122 \if\UmlautCode#1\@umlautaction\else
3123 \if\GraveCode#1\@graveaction\else
3124 \if\AcuteCode#1\@acuteaction\else
3125 \if\MacronCode#1\@macronaction\else
3126 \if\OverdotCode#1\@overdotaction\else
3127 \if\LeftBraceCode#1\@leftbraceaction\else
3128 \if\RightBraceCode#1\@rightbraceaction\else
3129 \if\UnderscoreCode#1\@underscoreaction\else
3130 \if\DaggerCode#1\@daggeraction\else
3131 \if\DoubleDaggerCode#1\@doubledaggeraction\else
3132 \if\SectionSymbolCode#1\@sectionsymbolaction\else
3133 \if\PilcrowCode#1\@pilcrowaction\else
3134 \if\LBCode#1\@lbaction\else
3135 \if\RBCode#1\@rbaction\else
3136 \if\BreveCode#1\@breveaction\else
3137 \if\CaronCode#1\@caronaction\else
3138 \if\DoubleAcuteCode#1\@doubleacuteaction\else
3139 \if\CedillaCode#1\@cedillaaction\else
3140 \if\UnderdotCode#1\@underdotaction\else
3141 \if\ArchJoinCode#1\@archjoinaction\else
3142 \if\LineUnderCode#1\@lineunderaction\else
3143 \if\CopyrightCode#1\@copyrightaction\else
3144 \if\PoundsCode#1\@poundsaction\else
3145 \if\AEscCode#1\@AEscaction\else
3146 \if\aescCode#1\@aescaction\else
3147 \if\OEthelCode#1\@OEthelaction\else
3148 \if\oethelCode#1\@oethelaction\else
3149 \if\AngstromCode#1\@Angstromaction\else
3150 \if\angstromCode#1\@angstromaction\else
3151 \if\SlashedOCode#1\@slashedOaction\else
3152 \if\SlashedoCode#1\@slashedoaction\else
3153 \if\BarredlCode#1\@barredlaction\else
3154 \if\BarredLCode#1\@barredLaction\else
3155 \if\EszettCode#1\@eszettaction\else
3156 \expandafter\@gobble#1\undecipherable%
3157 \fi
3158 \fi
3159 \fi
3160 \fi
3161 \fi
3162 \fi
3163 \fi
3164 \fi
3165 \fi
3166 \fi
3167 \fi
3168 \fi
3169 \fi
3170 \fi
3171 \fi
3172 \fi
3173 \fi
3174 \fi
3175 \fi
3176 \fi
3177 \fi
3178 \fi
3179 \fi
3180 \fi
3181 \fi
3182 \fi
3183 \fi
3184 \fi
3185 \fi
3186 \fi
3187 \fi
3188 \fi
3189 \fi
3190 \fi
3191 \fi
3192 \fi
3193 \fi
3194 \fi
3195 \fi
3196 \fi
3197 \fi
3198 \fi
3199 \fi
3200 }
3201 % \end{macrocode}
3202 % \end{macro}
3203
3204 % \begin{macro}{\@getnextword}
3205 % A low-level routine designed to extract the next [space-delimited]
3206 % word of the primary
3207 % argument. It has several quirks: if the passed string has one leading
3208 % space, it is included as part of next word. If it has two leading
3209 % [hard]spaces, the 2$^\mathrm{nd}$ hard space \textit{is} the next word.
3210 % Using the higher-level |\getnextword| deals automatically with
3211 % these abberant possibilities.
3212 % \begin{macrocode}
3213 \newcommand\@getnextword[2][v]{%
3214 \defaultTreatments%
3215 \def\SeekBlankSpace{2}%
3216 \substring[#1]{#2}{1}{\@MAXSTRINGSIZE}%
3217 \def\SeekBlankSpace{0}%
3218 }
3219 % \end{macrocode}
3220 % \end{macro}
3221
3222 % \begin{macro}{\@retokenizechar}
3223 % This command is the guts of the retokenize command. It grabs the
3224 % character provided in string |#1| and assigns it to a unique token
3225 % whose name is created from the string |#2|. The command has two
3226 % primary |\if| branches. The first branch is taken if the
3227 % character is a special two-byte-encoded escape-sequence, while
3228 % the second branch is taken if the character is a |&|, |%|, |#|,
3229 % a blankspace, or any simple one-byte character.
3230 % \begin{macrocode}
3231 \newcommand\@retokenizechar[2]{%
3232 \isnextbyte[q]{\EscapeChar}{#1}%
3233 \if T\theresult%
3234 \edef\@ESCcode{\expandafter\@gobble#1}%
3235 \if\UvariCode\@ESCcode%
3236 \expandafter\def\csname#2\endcsname{\Uvari}\else
3237 \if\UvariiCode\@ESCcode%
3238 \expandafter\def\csname#2\endcsname{\Uvarii}\else
3239 \if\UvariiiCode\@ESCcode%
3240 \expandafter\def\csname#2\endcsname{\Uvariii}\else
3241 \if\PipeCode\@ESCcode%
3242 \expandafter\def\csname#2\endcsname{\Pipe}\else
3243 \if\DollarCode\@ESCcode%
3244 \expandafter\def\csname#2\endcsname{\$}\else
3245 \if\CaratCode\@ESCcode%
3246 \expandafter\def\csname#2\endcsname{\Carat}\else
3247 \if\CircumflexCode\@ESCcode%
3248 \expandafter\def\csname#2\endcsname{\^}\else
3249 \if\TildeCode\@ESCcode%
3250 \expandafter\def\csname#2\endcsname{\~}\else
3251 \if\UmlautCode\@ESCcode%
3252 \expandafter\def\csname#2\endcsname{\"}\else
3253 \if\GraveCode\@ESCcode%
3254 \expandafter\def\csname#2\endcsname{\`}\else
3255 \if\AcuteCode\@ESCcode%
3256 \expandafter\def\csname#2\endcsname{\'}\else
3257 \if\MacronCode\@ESCcode%
3258 \expandafter\def\csname#2\endcsname{\=}\else
3259 \if\OverdotCode\@ESCcode%
3260 \expandafter\def\csname#2\endcsname{\.}\else
3261 \if\LeftBraceCode\@ESCcode%
3262 \expandafter\def\csname#2\endcsname{\{}\else
3263 \if\RightBraceCode\@ESCcode%
3264 \expandafter\def\csname#2\endcsname{\}}\else
3265 \if\UnderscoreCode\@ESCcode%
3266 \expandafter\def\csname#2\endcsname{\_}\else
3267 \if\DaggerCode\@ESCcode%
3268 \expandafter\def\csname#2\endcsname{\dag}\else
3269 \if\DoubleDaggerCode\@ESCcode%
3270 \expandafter\def\csname#2\endcsname{\ddag}\else
3271 \if\SectionSymbolCode\@ESCcode%
3272 \expandafter\def\csname#2\endcsname{\S}\else
3273 \if\PilcrowCode\@ESCcode%
3274 \expandafter\def\csname#2\endcsname{\P}\else
3275 \if\LBCode\@ESCcode%
3276 \expandafter\def\csname#2\endcsname{\SaveLB}\else
3277 \if\RBCode\@ESCcode%
3278 \expandafter\def\csname#2\endcsname{\SaveRB}\else
3279 \if\BreveCode\@ESCcode\expandafter\def\csname#2\endcsname{\u}\else
3280 \if\CaronCode\@ESCcode\expandafter\def\csname#2\endcsname{\v}\else
3281 \if\DoubleAcuteCode\@ESCcode\expandafter\def\csname#2\endcsname{\H}\else
3282 \if\CedillaCode\@ESCcode\expandafter\def\csname#2\endcsname{\c}\else
3283 \if\UnderdotCode\@ESCcode\expandafter\def\csname#2\endcsname{\d}\else
3284 \if\ArchJoinCode\@ESCcode\expandafter\def\csname#2\endcsname{\t}\else
3285 \if\LineUnderCode\@ESCcode\expandafter\def\csname#2\endcsname{\b}\else
3286 \if\CopyrightCode\@ESCcode\expandafter\def\csname#2\endcsname{\copyright}\else
3287 \if\PoundsCode\@ESCcode\expandafter\def\csname#2\endcsname{\pounds}\else
3288 \if\AEscCode\@ESCcode\expandafter\def\csname#2\endcsname{\AE}\else
3289 \if\aescCode\@ESCcode\expandafter\def\csname#2\endcsname{\ae}\else
3290 \if\OEthelCode\@ESCcode\expandafter\def\csname#2\endcsname{\OE}\else
3291 \if\oethelCode\@ESCcode\expandafter\def\csname#2\endcsname{\oe}\else
3292 \if\AngstromCode\@ESCcode\expandafter\def\csname#2\endcsname{\AA}\else
3293 \if\angstromCode\@ESCcode\expandafter\def\csname#2\endcsname{\aa}\else
3294 \if\SlashedOCode\@ESCcode\expandafter\def\csname#2\endcsname{\O}\else
3295 \if\SlashedoCode\@ESCcode\expandafter\def\csname#2\endcsname{\o}\else
3296 \if\BarredlCode\@ESCcode\expandafter\def\csname#2\endcsname{\l}\else
3297 \if\BarredLCode\@ESCcode\expandafter\def\csname#2\endcsname{\L}\else
3298 \if\EszettCode\@ESCcode\expandafter\def\csname#2\endcsname{\ss}\else
3299 \expandafter\def\csname#2\endcsname{\undecipherable}%
3300 \fi
3301 \fi
3302 \fi
3303 \fi
3304 \fi
3305 \fi
3306 \fi
3307 \fi
3308 \fi
3309 \fi
3310 \fi
3311 \fi
3312 \fi
3313 \fi
3314 \fi
3315 \fi
3316 \fi
3317 \fi
3318 \fi
3319 \fi
3320 \fi
3321 \fi
3322 \fi
3323 \fi
3324 \fi
3325 \fi
3326 \fi
3327 \fi
3328 \fi
3329 \fi
3330 \fi
3331 \fi
3332 \fi
3333 \fi
3334 \fi
3335 \fi
3336 \fi
3337 \fi
3338 \fi
3339 \fi
3340 \fi
3341 \fi
3342 \else
3343 \expandafter\ifx\expandafter\&#1%
3344 \expandafter\def\csname#2\endcsname{\&}\else
3345 \expandafter\ifx\expandafter\%#1%
3346 \expandafter\def\csname#2\endcsname{\%}\else
3347 \expandafter\ifx\expandafter\##1%
3348 \expandafter\def\csname#2\endcsname{\#}\else
3349 \if\EncodedBlankSpace#1\expandafter\def\csname#2\endcsname{\ }\else
3350 \expandafter\edef\csname#2\endcsname{#1}%
3351 \fi
3352 \fi
3353 \fi
3354 \fi
3355 \fi
3356 }
3357 % \end{macrocode}
3358 % \end{macro}
3359
3360 % \begin{macro}{\@defineactions}
3361 % This routine defines how encoded characters are to be treated by the
3362 % |\ESCrotate| routine, depending on the [encoding, capitalization,
3363 % blank, symbol, \textit{etc.}] treatments that have
3364 % been \textit{a priori} specified.
3365 % \begin{macrocode}
3366 % \@blankaction AND OTHER ...action'S ARE SET, DEPENDING ON VALUES OF
3367 % TREATMENT FLAGS. CHARS ARE EITHER ENCODED, DECODED, OR REMOVED.
3368 \newcommand\@defineactions{%
3369 % SET UP TREATMENT FOR SPACES, ENCODED SPACES, AND [REENCODED] SYMBOLS
3370 \if e\EncodingTreatment%
3371 % ENCODE SPACES, KEEP ENCODED SPACES ENCODED, ENCODE SYMBOLS.
3372 \edef\@blankaction{\EncodedBlankSpace}%
3373 \def\@dollaraction{\EncodedDollar}%
3374 \def\@pipeaction{\EncodedPipe}%
3375 \def\@uvariaction{\EncodedUvari}%
3376 \def\@uvariiaction{\EncodedUvarii}%
3377 \def\@uvariiiaction{\EncodedUvariii}%
3378 \def\@carataction{\EncodedCarat}%
3379 \def\@circumflexaction{\EncodedCircumflex}%
3380 \def\@tildeaction{\EncodedTilde}%
3381 \def\@umlautaction{\EncodedUmlaut}%
3382 \def\@graveaction{\EncodedGrave}%
3383 \def\@acuteaction{\EncodedAcute}%
3384 \def\@macronaction{\EncodedMacron}%
3385 \def\@overdotaction{\EncodedOverdot}%
3386 \def\@breveaction{\EncodedBreve}%
3387 \def\@caronaction{\EncodedCaron}%
3388 \def\@doubleacuteaction{\EncodedDoubleAcute}%
3389 \def\@cedillaaction{\EncodedCedilla}%
3390 \def\@underdotaction{\EncodedUnderdot}%
3391 \def\@archjoinaction{\EncodedArchJoin}%
3392 \def\@lineunderaction{\EncodedLineUnder}%
3393 \def\@copyrightaction{\EncodedCopyright}%
3394 \def\@poundsaction{\EncodedPounds}%
3395 \def\@leftbraceaction{\EncodedLeftBrace}%
3396 \def\@rightbraceaction{\EncodedRightBrace}%
3397 \def\@underscoreaction{\EncodedUnderscore}%
3398 \def\@daggeraction{\EncodedDagger}%
3399 \def\@doubledaggeraction{\EncodedDoubleDagger}%
3400 \def\@sectionsymbolaction{\EncodedSectionSymbol}%
3401 \def\@pilcrowaction{\EncodedPilcrow}%
3402 \def\@eszettaction{\EncodedEszett}%
3403 \def\@lbaction{\EncodedLB}%
3404 \def\@rbaction{\EncodedRB}%
3405 \if 2\AlphaCapsTreatment%
3406 \def\@AEscaction{\Encodedaesc}%
3407 \def\@OEthelaction{\Encodedoethel}%
3408 \def\@Angstromaction{\Encodedangstrom}%
3409 \def\@slashedOaction{\EncodedSlashedo}%
3410 \def\@barredLaction{\EncodedBarredl}%
3411 \else
3412 \def\@AEscaction{\EncodedAEsc}%
3413 \def\@OEthelaction{\EncodedOEthel}%
3414 \def\@Angstromaction{\EncodedAngstrom}%
3415 \def\@slashedOaction{\EncodedSlashedO}%
3416 \def\@barredLaction{\EncodedBarredL}%
3417 \fi
3418 \if 2\AlphaTreatment%
3419 \def\@aescaction{\EncodedAEsc}%
3420 \def\@oethelaction{\EncodedOEthel}%
3421 \def\@angstromaction{\EncodedAngstrom}%
3422 \def\@slashedoaction{\EncodedSlashedO}%
3423 \def\@barredlaction{\EncodedBarredL}%
3424 \else
3425 \def\@aescaction{\Encodedaesc}%
3426 \def\@oethelaction{\Encodedoethel}%
3427 \def\@angstromaction{\Encodedangstrom}%
3428 \def\@slashedoaction{\EncodedSlashedo}%
3429 \def\@barredlaction{\EncodedBarredl}%
3430 \fi
3431 \else
3432 % EncodingTreatment=v or q:
3433 % LEAVE SPACES ALONE; RESTORE ENCODED SPACES AND SYMBOLS
3434 \def\@blankaction{\BlankSpace}%
3435 \def\@dollaraction{\Dollar}%
3436 \def\@pipeaction{\Pipe}%
3437 \def\@uvariaction{\Uvari}%
3438 \def\@uvariiaction{\Uvarii}%
3439 \def\@uvariiiaction{\Uvariii}%
3440 \def\@carataction{\Carat}%
3441 \def\@circumflexaction{\Circumflex}%
3442 \def\@tildeaction{\Tilde}%
3443 \def\@umlautaction{\Umlaut}%
3444 \def\@graveaction{\Grave}%
3445 \def\@acuteaction{\Acute}%
3446 \def\@macronaction{\Macron}%
3447 \def\@overdotaction{\Overdot}%
3448 \def\@breveaction{\Breve}%
3449 \def\@caronaction{\Caron}%
3450 \def\@doubleacuteaction{\DoubleAcute}%
3451 \def\@cedillaaction{\Cedilla}%
3452 \def\@underdotaction{\Underdot}%
3453 \def\@archjoinaction{\ArchJoin}%
3454 \def\@lineunderaction{\LineUnder}%
3455 \def\@copyrightaction{\Copyright}%
3456 \def\@poundsaction{\Pounds}%
3457 \def\@leftbraceaction{\LeftBrace}%
3458 \def\@rightbraceaction{\RightBrace}%
3459 \def\@underscoreaction{\Underscore}%
3460 \def\@daggeraction{\Dagger}%
3461 \def\@doubledaggeraction{\DoubleDagger}%
3462 \def\@sectionsymbolaction{\SectionSymbol}%
3463 \def\@pilcrowaction{\Pilcrow}%
3464 \def\@eszettaction{\Eszett}%
3465 \def\@lbaction{\UnencodedLB}%
3466 \def\@rbaction{\UnencodedRB}%
3467 \if 2\AlphaCapsTreatment%
3468 \def\@AEscaction{\aesc}%
3469 \def\@OEthelaction{\oethel}%
3470 \def\@Angstromaction{\angstrom}%
3471 \def\@slashedOaction{\Slashedo}%
3472 \def\@barredLaction{\Barredl}%
3473 \else
3474 \def\@AEscaction{\AEsc}%
3475 \def\@OEthelaction{\OEthel}%
3476 \def\@Angstromaction{\Angstrom}%
3477 \def\@slashedOaction{\SlashedO}%
3478 \def\@barredLaction{\BarredL}%
3479 \fi
3480 \if 2\AlphaTreatment%
3481 \def\@aescaction{\AEsc}%
3482 \def\@oethelaction{\OEthel}%
3483 \def\@angstromaction{\Angstrom}%
3484 \def\@slashedoaction{\SlashedO}%
3485 \def\@barredlaction{\BarredL}%
3486 \else
3487 \def\@aescaction{\aesc}%
3488 \def\@oethelaction{\oethel}%
3489 \def\@angstromaction{\angstrom}%
3490 \def\@slashedoaction{\Slashedo}%
3491 \def\@barredlaction{\Barredl}%
3492 \fi
3493 \fi
3494 % REMOVE SPACES AND ENCODED SPACES?
3495 \if 0\BlankTreatment%
3496 \edef\@blankaction{}%
3497 \fi
3498 % REMOVE ENCODED SYMBOLS?
3499 \if 0\SymbolTreatment%
3500 \def\@dollaraction{}%
3501 \def\@pipeaction{}%
3502 \def\@carataction{}%
3503 \def\@circumflexaction{}%
3504 \def\@tildeaction{}%
3505 \def\@umlautaction{}%
3506 \def\@graveaction{}%
3507 \def\@acuteaction{}%
3508 \def\@macronaction{}%
3509 \def\@overdotaction{}%
3510 \def\@breveaction{}%
3511 \def\@caronaction{}%
3512 \def\@doubleacuteaction{}%
3513 \def\@cedillaaction{}%
3514 \def\@underdotaction{}%
3515 \def\@archjoinaction{}%
3516 \def\@lineunderaction{}%
3517 \def\@copyrightaction{}%
3518 \def\@poundsaction{}%
3519 \def\@leftbraceaction{}%
3520 \def\@rightbraceaction{}%
3521 \def\@underscoreaction{}%
3522 \def\@daggeraction{}%
3523 \def\@doubledaggeraction{}%
3524 \def\@sectionsymbolaction{}%
3525 \def\@pilcrowaction{}%
3526 \def\@lbaction{}%
3527 \def\@rbaction{}%
3528 \fi
3529 % REMOVE ENCODED ALPHACAPS?
3530 \if 0\AlphaCapsTreatment%
3531 \def\@AEscaction{}%
3532 \def\@OEthelaction{}%
3533 \def\@Angstromaction{}%
3534 \def\@slashedOaction{}%
3535 \def\@barredLaction{}%
3536 \fi
3537 % REMOVE ENCODED ALPHA?
3538 \if 0\AlphaTreatment%
3539 \def\@aescaction{}%
3540 \def\@oethelaction{}%
3541 \def\@angstromaction{}%
3542 \def\@slashedoaction{}%
3543 \def\@barredlaction{}%
3544 \def\@eszettaction{}%
3545 \fi
3546 }
3547 % \end{macrocode}
3548 % \end{macro}
3549
3550 % \begin{macro}{\@forcecapson}
3551 % Force capitalization of strings processed by |\substring| for the
3552 % time being.
3553 % \begin{macrocode}
3554 \newcommand\@forcecapson{%
3555 \def\AlphaTreatment{2}%
3556 \def\AlphaCapsTreatment{1}%
3557 }
3558 % \end{macrocode}
3559 % \end{macro}
3560
3561 % \begin{macro}{\@relaxcapson}
3562 % Restore prior treatments following a period of enforced capitalization.
3563 % \begin{macrocode}
3564 \newcommand\@relaxcapson{%
3565 \let\AlphaTreatment\SaveAlphaTreatment%
3566 \let\AlphaCapsTreatment\SaveAlphaCapsTreatment%
3567 \@defineactions%
3568 }
3569 % \end{macrocode}
3570 % \end{macro}
3571
3572 % \begin{macro}{\@decodepointer}
3573 % As pertains to arguments 3 and 4 of |\substring|, this routine
3574 % implements use of the |$| character to mean END-OF-STRING,
3575 % and |$-{|\textit{integer}|}| for addressing relative to the
3576 % END-OF-STRING.
3577 % \begin{macrocode}
3578 \newcommand\@decodepointer[2][\value{@stringsize}]{%
3579 \isnextbyte[q]{$}{#2}%
3580 \if T\theresult%
3581 \isnextbyte[q]{-}{\expandafter\@gobble#2}%
3582 \if T\theresult%
3583 \setcounter{@@@letterindex}{#1}%
3584 \@gobblearg{#2}{2}%
3585 \addtocounter{@@@letterindex}{-\gobbledword}%
3586 \edef\@fromtoindex{\value{@@@letterindex}}%
3587 \else
3588 \edef\@fromtoindex{#1}%
3589 \fi
3590 \else
3591 \edef\@fromtoindex{#2}%
3592 \fi
3593 }
3594 % \end{macrocode}
3595 % \end{macro}
3596
3597 % \begin{macro}{\@getstringlength}
3598 % Get's string length of |#1|, puts result in counter |#2|.
3599 % \begin{macrocode}
3600 \newcommand\@getstringlength[2]{%
3601 \edef\@@teststring{#1\endofstring}%
3602 \ifthenelse{\equal{\@@teststring}{\endofstring}}%
3603 {\setcounter{#2}{0}}%
3604 {%
3605 \setcounter{@gobblesize}{1}%
3606 \whiledo{\value{@gobblesize} < \@MAXSTRINGSIZE}{%
3607 %
3608 \@gobblearg{\@@teststring}{1}%
3609 \edef\@@teststring{\gobbledword}%
3610 \ifthenelse{\equal{\@@teststring}{\endofstring}}%
3611 {\setcounter{#2}{\value{@gobblesize}}%
3612 \setcounter{@gobblesize}{\@MAXSTRINGSIZE}}%
3613 {\addtocounter{@gobblesize}{1}}%
3614 }%
3615 }%
3616 }
3617 % \end{macrocode}
3618 % \end{macro}
3619
3620 % \begin{macro}{\@gobblearg}
3621 % Gobble first |#2| characters from string |#1|. The
3622 % result is stored in |\gobbledword|. Two-byte escape sequences,
3623 % when encountered, count as a single gobble.
3624 % \begin{macrocode}
3625 \newcommand\@gobblearg[2]{%
3626 \setcounter{@letterindex}{0}%
3627 \setcounter{@gobbleindex}{#2}%
3628 \edef\gobbledword{#1}%
3629 \whiledo{\value{@letterindex} < \value{@gobbleindex}}{%
3630 \isnextbyte[q]{\EscapeChar}{\gobbledword}%
3631 \if T\theresult%
3632 % GOBBLE ESCAPE CHARACTER
3633 \edef\gobbledword{\@DiscardNextChar{\gobbledword}}%
3634 \fi
3635 % GOBBLE NORMAL CHARACTER OR ESCAPE CODE
3636 \edef\gobbledword{\@DiscardNextChar{\gobbledword}}%
3637 \addtocounter{@letterindex}{1}%
3638 }%
3639 }
3640 % \end{macrocode}
3641 % \end{macro}
3642
3643 % \begin{macro}{\@DiscardNextChar}
3644 % Remove the next character from the argument string. Since
3645 % |\@gobble| skips spaces, the routine must first look for the case of
3646 % a leading blankspace. If none is found, proceed with a normal
3647 % |\@gobble|. Note: as per \LaTeX{} convention, |\@DiscardNextChar|
3648 % treats double/multi-softspaces as single space.
3649 % \begin{macrocode}
3650 \newcommand\@DiscardNextChar[1]{%
3651 \expandafter\if\expandafter\BlankSpace#1\else
3652 \expandafter\@gobble#1%
3653 \fi
3654 }
3655 % \end{macrocode}
3656 % \end{macro}
3657
3658 % \begin{macro}{\@convertsymboltostring}
3659 % Routine for converting an encodable symbol (|#3|) into string (|#4|),
3660 % for every occurance in the given string |#2|.
3661 % \begin{macrocode}
3662 \newcommand\@convertsymboltostring[4][v]{%
3663 \def\@fromcode{#3}%
3664 \def\@tostring{#4}%
3665 \def\EncodingTreatment{e}%
3666 \substring[e]{#2}{1}{\@MAXSTRINGSIZE}%
3667 \@convertoff%
3668 \if e#1\else\substring[#1]{\thestring}{1}{\@MAXSTRINGSIZE}\fi%
3669 }
3670 % \end{macrocode}
3671 % \end{macro}
3672
3673 % \begin{macro}{\@convertbytetostring}
3674 % Routine for converting an plain byte (|#3|) into string (|#4|),
3675 % for every occurance in the given string |#2|.
3676 % \begin{macrocode}
3677 \newcommand\@convertbytetostring[4][v]{%
3678 \def\@frombyte{#3}%
3679 \def\@tostring{#4}%
3680 \def\EncodingTreatment{e}%
3681 \substring[e]{#2}{1}{\@MAXSTRINGSIZE}%
3682 \@convertoff%
3683 \if e#1\else\substring[#1]{\thestring}{1}{\@MAXSTRINGSIZE}\fi%
3684 }
3685 % \end{macrocode}
3686 % \end{macro}
3687
3688 % \begin{macro}{\@treatleadingspaces}
3689 % This routine will address the leading spaces of string |#2|. If
3690 % argument |#3| is an 'x' character, those leading spaces will be
3691 % deleted from the string. Otherwise, those leading spaces will be
3692 % rotated to the end of the string.
3693 % \begin{macrocode}
3694 \newcommand\@treatleadingspaces[3][v]{\+%
3695 \defaultTreatments%
3696 \edef\thestring{#2}%
3697 \@getstringlength{\thestring}{@stringsize}%
3698 \setcounter{@maxrotation}{\value{@stringsize}}%
3699 \setcounter{@letterindex}{0}%
3700 \whiledo{\value{@letterindex} < \value{@maxrotation}}{%
3701 \addtocounter{@letterindex}{1}%
3702 \isnextbyte[q]{\EncodedBlankSpace}{\thestring}%
3703 \if F\theresult\isnextbyte[q]{\BlankSpace}{\thestring}\fi%
3704 \if T\theresult%
3705 \isnextbyte[q]{#3}{x}%
3706 \if F\theresult%
3707 % NORMAL OR ENCODED BLANK... ROTATE IT
3708 \edef\thestring{\@rotate{\thestring}}%
3709 \else
3710 % NORMAL OR ENCODED BLANK... DELETE IT (IF 3rd ARG=X)
3711 \@gobblearg{\thestring}{1}%
3712 \edef\thestring{\gobbledword}%
3713 \fi
3714 \else
3715 \setcounter{@maxrotation}{\value{@letterindex}}%
3716 \fi
3717 }\?%
3718 \substring[#1]{\thestring}{1}{\@MAXSTRINGSIZE}%
3719 }
3720 % \end{macrocode}
3721 % \end{macro}
3722
3723 % \begin{macro}{\@convertoff}
3724 % This routine is an initialization routine to
3725 % guarantee that there is no conversion of |\@frombyte| to |\@tostring|,
3726 % until further notice. It accomplishes this
3727 % by setting up such that subsequent |\if\@frombyte| and
3728 % |\if\@fromcode| clauses will automatically fail.
3729 % \begin{macrocode}
3730 \newcommand\@convertoff{\def\@frombyte{xy}\def\@tostring{}%
3731 \def\@fromcode{xy}}
3732 \@convertoff
3733 % \end{macrocode}
3734 % \end{macro}
3735
3736 % \begin{macro}{\@rotate}
3737 % The following code is the engine of the string manipulation routine.
3738 % It is a tree of successive \LaTeX{} commands (each of which is
3739 % composed of an |\if...| cascade) which have the net
3740 % effect of rotating the first letter of the string into the last
3741 % position. Depending on modes set by |\@defineactions| and
3742 % |\defaultTreatments|, the leading character is either encoded,
3743 % decoded, or removed in the process.
3744 % Note: |\@rotate| loses track of double/multi-spaces, per \LaTeX{}
3745 % convention, unless encoded blanks (|~|) are used.
3746 % \begin{macrocode}
3747 \newcommand\@rotate[1]{%
3748 % CHECK BYTE CONVERSION TEST FIRST
3749 \if \@frombyte#1\@tostring\else
3750 % MUST CHECK FOR MULTI-BYTE CHARACTERS NEXT, SO THAT ENCODING CHARACTER
3751 % ISN'T MISTAKEN FOR A NORMAL CHARACTER LATER IN MACRO.
3752 \if 0\SymbolTreatment%
3753 \@removeExpandableSymbols{#1}%
3754 \else
3755 \@rotateExpandableSymbols{#1}%
3756 \fi
3757 \fi
3758 }
3759
3760 \newcommand\@rotateExpandableSymbols[1]{%
3761 % INDIRECT (EXPANDABLE) SYMBOLS
3762 \expandafter\ifx\expandafter\&#1\&\else
3763 \expandafter\ifx\expandafter\%#1\%\else
3764 \expandafter\ifx\expandafter\##1\#\else
3765 \@rotateBlankSpaces{#1}%
3766 \fi
3767 \fi
3768 \fi
3769 }
3770
3771 \newcommand\@removeExpandableSymbols[1]{%
3772 % INDIRECT (EXPANDABLE) SYMBOLS
3773 \expandafter\ifx\expandafter\&#1\else
3774 \expandafter\ifx\expandafter\%#1\else
3775 \expandafter\ifx\expandafter\##1\else
3776 \@rotateBlankSpaces{#1}%
3777 \fi
3778 \fi
3779 \fi
3780 }
3781
3782 \newcommand\@rotateBlankSpaces[1]{%
3783 \expandafter\ifx\expandafter$#1$\else% <---RETAIN GOING INTO/FROM MATH MODE
3784 % THE FOLLOWING FINDS TILDES, BUT MUST COME AFTER EXPANDABLE SYMBOL
3785 % SEARCH, OR ELSE IT FINDS THEM TOO, BY MISTAKE.
3786 \if \EncodedBlankSpace#1\@blankaction\else% <--- FINDS REENCODED TILDE
3787 % THE FOLLOWING SHOULD FIND TILDES, BUT DOESN'T... THUS, COMMENTED OUT.
3788 % \expandafter\ifx\expandafter\EncodedBlankSpace#1\@blankaction\else
3789 \if \BlankSpace#1\@blankaction\else
3790 \if 2\AlphaTreatment%
3791 \@chcaseAlpha{#1}%
3792 \else
3793 \if 0\AlphaTreatment%
3794 \@removeAlpha{#1}%
3795 \else
3796 \@rotateAlpha{#1}%
3797 \fi
3798 \fi
3799 \fi
3800 % \fi
3801 \fi
3802 \fi
3803 }
3804
3805 \newcommand\@rotateAlpha[1]{%
3806 % LOWERCASE
3807 \if a#1a\else
3808 \if b#1b\else
3809 \if c#1c\else
3810 \if d#1d\else
3811 \if e#1e\else
3812 \if f#1f\else
3813 \if g#1g\else
3814 \if h#1h\else
3815 \if i#1i\else
3816 \if j#1j\else
3817 \if k#1k\else
3818 \if l#1l\else
3819 \if m#1m\else
3820 \if n#1n\else
3821 \if o#1o\else
3822 \if p#1p\else
3823 \if q#1q\else
3824 \if r#1r\else
3825 \if s#1s\else
3826 \if t#1t\else
3827 \if u#1u\else
3828 \if v#1v\else
3829 \if w#1w\else
3830 \if x#1x\else
3831 \if y#1y\else
3832 \if z#1z\else
3833 \if 2\AlphaCapsTreatment%
3834 \@chcaseAlphaCaps{#1}%
3835 \else
3836 \if 0\AlphaCapsTreatment%
3837 \@removeAlphaCaps{#1}%
3838 \else
3839 \@rotateAlphaCaps{#1}%
3840 \fi
3841 \fi
3842 \fi
3843 \fi
3844 \fi
3845 \fi
3846 \fi
3847 \fi
3848 \fi
3849 \fi
3850 \fi
3851 \fi
3852 \fi
3853 \fi
3854 \fi
3855 \fi
3856 \fi
3857 \fi
3858 \fi
3859 \fi
3860 \fi
3861 \fi
3862 \fi
3863 \fi
3864 \fi
3865 \fi
3866 \fi
3867 \fi
3868 }
3869
3870 \newcommand\@removeAlpha[1]{%
3871 % LOWERCASE
3872 \if a#1\else
3873 \if b#1\else
3874 \if c#1\else
3875 \if d#1\else
3876 \if e#1\else
3877 \if f#1\else
3878 \if g#1\else
3879 \if h#1\else
3880 \if i#1\else
3881 \if j#1\else
3882 \if k#1\else
3883 \if l#1\else
3884 \if m#1\else
3885 \if n#1\else
3886 \if o#1\else
3887 \if p#1\else
3888 \if q#1\else
3889 \if r#1\else
3890 \if s#1\else
3891 \if t#1\else
3892 \if u#1\else
3893 \if v#1\else
3894 \if w#1\else
3895 \if x#1\else
3896 \if y#1\else
3897 \if z#1\else
3898 \if 2\AlphaCapsTreatment%
3899 \@chcaseAlphaCaps{#1}%
3900 \else
3901 \if 0\AlphaCapsTreatment%
3902 \@removeAlphaCaps{#1}%
3903 \else
3904 \@rotateAlphaCaps{#1}%
3905 \fi
3906 \fi
3907 \fi
3908 \fi
3909 \fi
3910 \fi
3911 \fi
3912 \fi
3913 \fi
3914 \fi
3915 \fi
3916 \fi
3917 \fi
3918 \fi
3919 \fi
3920 \fi
3921 \fi
3922 \fi
3923 \fi
3924 \fi
3925 \fi
3926 \fi
3927 \fi
3928 \fi
3929 \fi
3930 \fi
3931 \fi
3932 \fi
3933 }
3934
3935 \newcommand\@chcaseAlpha[1]{%
3936 % LOWERCASE TO UPPERCASE
3937 \if a#1A\else
3938 \if b#1B\else
3939 \if c#1C\else
3940 \if d#1D\else
3941 \if e#1E\else
3942 \if f#1F\else
3943 \if g#1G\else
3944 \if h#1H\else
3945 \if i#1I\else
3946 \if j#1J\else
3947 \if k#1K\else
3948 \if l#1L\else
3949 \if m#1M\else
3950 \if n#1N\else
3951 \if o#1O\else
3952 \if p#1P\else
3953 \if q#1Q\else
3954 \if r#1R\else
3955 \if s#1S\else
3956 \if t#1T\else
3957 \if u#1U\else
3958 \if v#1V\else
3959 \if w#1W\else
3960 \if x#1X\else
3961 \if y#1Y\else
3962 \if z#1Z\else
3963 \if 2\AlphaCapsTreatment%
3964 \@chcaseAlphaCaps{#1}%
3965 \else
3966 \if 0\AlphaCapsTreatment%
3967 \@removeAlphaCaps{#1}%
3968 \else
3969 \@rotateAlphaCaps{#1}%
3970 \fi
3971 \fi
3972 \fi
3973 \fi
3974 \fi
3975 \fi
3976 \fi
3977 \fi
3978 \fi
3979 \fi
3980 \fi
3981 \fi
3982 \fi
3983 \fi
3984 \fi
3985 \fi
3986 \fi
3987 \fi
3988 \fi
3989 \fi
3990 \fi
3991 \fi
3992 \fi
3993 \fi
3994 \fi
3995 \fi
3996 \fi
3997 \fi
3998 }
3999
4000 \newcommand\@rotateAlphaCaps[1]{%
4001 % UPPERCASE
4002 \if A#1A\else
4003 \if B#1B\else
4004 \if C#1C\else
4005 \if D#1D\else
4006 \if E#1E\else
4007 \if F#1F\else
4008 \if G#1G\else
4009 \if H#1H\else
4010 \if I#1I\else
4011 \if J#1J\else
4012 \if K#1K\else
4013 \if L#1L\else
4014 \if M#1M\else
4015 \if N#1N\else
4016 \if O#1O\else
4017 \if P#1P\else
4018 \if Q#1Q\else
4019 \if R#1R\else
4020 \if S#1S\else
4021 \if T#1T\else
4022 \if U#1U\else
4023 \if V#1V\else
4024 \if W#1W\else
4025 \if X#1X\else
4026 \if Y#1Y\else
4027 \if Z#1Z\else
4028 \if 0\NumeralTreatment%
4029 \@removeNumerals{#1}%
4030 \else
4031 \@rotateNumerals{#1}%
4032 \fi
4033 \fi
4034 \fi
4035 \fi
4036 \fi
4037 \fi
4038 \fi
4039 \fi
4040 \fi
4041 \fi
4042 \fi
4043 \fi
4044 \fi
4045 \fi
4046 \fi
4047 \fi
4048 \fi
4049 \fi
4050 \fi
4051 \fi
4052 \fi
4053 \fi
4054 \fi
4055 \fi
4056 \fi
4057 \fi
4058 \fi
4059 }
4060
4061 \newcommand\@removeAlphaCaps[1]{%
4062 % UPPERCASE
4063 \if A#1\else
4064 \if B#1\else
4065 \if C#1\else
4066 \if D#1\else
4067 \if E#1\else
4068 \if F#1\else
4069 \if G#1\else
4070 \if H#1\else
4071 \if I#1\else
4072 \if J#1\else
4073 \if K#1\else
4074 \if L#1\else
4075 \if M#1\else
4076 \if N#1\else
4077 \if O#1\else
4078 \if P#1\else
4079 \if Q#1\else
4080 \if R#1\else
4081 \if S#1\else
4082 \if T#1\else
4083 \if U#1\else
4084 \if V#1\else
4085 \if W#1\else
4086 \if X#1\else
4087 \if Y#1\else
4088 \if Z#1\else
4089 \if 0\NumeralTreatment%
4090 \@removeNumerals{#1}%
4091 \else
4092 \@rotateNumerals{#1}%
4093 \fi
4094 \fi
4095 \fi
4096 \fi
4097 \fi
4098 \fi
4099 \fi
4100 \fi
4101 \fi
4102 \fi
4103 \fi
4104 \fi
4105 \fi
4106 \fi
4107 \fi
4108 \fi
4109 \fi
4110 \fi
4111 \fi
4112 \fi
4113 \fi
4114 \fi
4115 \fi
4116 \fi
4117 \fi
4118 \fi
4119 \fi
4120 }
4121
4122 \newcommand\@chcaseAlphaCaps[1]{%
4123 % UPPERCASE TO LOWERCASE
4124 \if A#1a\else
4125 \if B#1b\else
4126 \if C#1c\else
4127 \if D#1d\else
4128 \if E#1e\else
4129 \if F#1f\else
4130 \if G#1g\else
4131 \if H#1h\else
4132 \if I#1i\else
4133 \if J#1j\else
4134 \if K#1k\else
4135 \if L#1l\else
4136 \if M#1m\else
4137 \if N#1n\else
4138 \if O#1o\else
4139 \if P#1p\else
4140 \if Q#1q\else
4141 \if R#1r\else
4142 \if S#1s\else
4143 \if T#1t\else
4144 \if U#1u\else
4145 \if V#1v\else
4146 \if W#1w\else
4147 \if X#1x\else
4148 \if Y#1y\else
4149 \if Z#1z\else
4150 \if 0\NumeralTreatment%
4151 \@removeNumerals{#1}%
4152 \else
4153 \@rotateNumerals{#1}%
4154 \fi
4155 \fi
4156 \fi
4157 \fi
4158 \fi
4159 \fi
4160 \fi
4161 \fi
4162 \fi
4163 \fi
4164 \fi
4165 \fi
4166 \fi
4167 \fi
4168 \fi
4169 \fi
4170 \fi
4171 \fi
4172 \fi
4173 \fi
4174 \fi
4175 \fi
4176 \fi
4177 \fi
4178 \fi
4179 \fi
4180 \fi
4181 }
4182
4183 \newcommand\@rotateNumerals[1]{%
4184 % NUMERALS
4185 \if 1#11\else
4186 \if 2#12\else
4187 \if 3#13\else
4188 \if 4#14\else
4189 \if 5#15\else
4190 \if 6#16\else
4191 \if 7#17\else
4192 \if 8#18\else
4193 \if 9#19\else
4194 \if 0#10\else
4195 \if 0\PunctuationTreatment%
4196 \@removePunctuation{#1}%
4197 \else
4198 \@rotatePunctuation{#1}%
4199 \fi
4200 \fi
4201 \fi
4202 \fi
4203 \fi
4204 \fi
4205 \fi
4206 \fi
4207 \fi
4208 \fi
4209 \fi
4210 }
4211
4212 \newcommand\@removeNumerals[1]{%
4213 % NUMERALS
4214 \if 1#1\else
4215 \if 2#1\else
4216 \if 3#1\else
4217 \if 4#1\else
4218 \if 5#1\else
4219 \if 6#1\else
4220 \if 7#1\else
4221 \if 8#1\else
4222 \if 9#1\else
4223 \if 0#1\else
4224 \if 0\PunctuationTreatment%
4225 \@removePunctuation{#1}%
4226 \else
4227 \@rotatePunctuation{#1}%
4228 \fi
4229 \fi
4230 \fi
4231 \fi
4232 \fi
4233 \fi
4234 \fi
4235 \fi
4236 \fi
4237 \fi
4238 \fi
4239 }
4240
4241 \newcommand\@rotatePunctuation[1]{%
4242 % PUNCTUATION
4243 \if ;#1;\else
4244 \if :#1:\else
4245 \if '#1'\else
4246 \if "#1"\else
4247 \if ,#1,\else
4248 \if .#1.\else
4249 \if ?#1?\else
4250 \if `#1`\else
4251 \if !#1!\else
4252 \if 0\SymbolTreatment%
4253 \@removeDirectSymbols{#1}%
4254 \else
4255 \@rotateDirectSymbols{#1}%
4256 \fi
4257 \fi
4258 \fi
4259 \fi
4260 \fi
4261 \fi
4262 \fi
4263 \fi
4264 \fi
4265 \fi
4266 }
4267
4268 \newcommand\@removePunctuation[1]{%
4269 % PUNCTUATION
4270 \if ;#1\else
4271 \if :#1\else
4272 \if '#1\else
4273 \if "#1\else
4274 \if ,#1\else
4275 \if .#1\else
4276 \if ?#1\else
4277 \if `#1\else
4278 \if !#1\else
4279 \if 0\SymbolTreatment%
4280 \@removeDirectSymbols{#1}%
4281 \else
4282 \@rotateDirectSymbols{#1}%
4283 \fi
4284 \fi
4285 \fi
4286 \fi
4287 \fi
4288 \fi
4289 \fi
4290 \fi
4291 \fi
4292 \fi
4293 }
4294
4295 \newcommand\@rotateDirectSymbols[1]{%
4296 % DIRECT SYMBOLS
4297 \if /#1/\else
4298 \if @#1@\else
4299 \if *#1*\else
4300 \if (#1(\else
4301 \if )#1)\else
4302 \if -#1-\else
4303 \if _#1_\else
4304 \if =#1=\else
4305 \if +#1+\else
4306 \if [#1[\else
4307 \if ]#1]\else
4308 \if ^#1^\else% <--FOR SUPERSCRIPTS, NOT \^
4309 \if <#1<\else
4310 \if >#1>\else
4311 \if |#1|\else
4312 \if &#1&\else
4313 \@rotateUndecipherable{#1}%
4314 \fi
4315 \fi
4316 \fi
4317 \fi
4318 \fi
4319 \fi
4320 \fi
4321 \fi
4322 \fi
4323 \fi
4324 \fi
4325 \fi
4326 \fi
4327 \fi
4328 \fi
4329 \fi
4330 }
4331
4332 \newcommand\@removeDirectSymbols[1]{%
4333 % DIRECT SYMBOLS
4334 \if /#1\else
4335 \if @#1\else
4336 \if *#1\else
4337 \if (#1\else
4338 \if )#1\else
4339 \if -#1\else
4340 \if _#1\else
4341 \if =#1\else
4342 \if +#1\else
4343 \if [#1\else
4344 \if ]#1\else
4345 \if ^#1\else% <--FOR SUPERSCRIPTS, NOT \^
4346 \if <#1\else
4347 \if >#1\else
4348 \if |#1\else
4349 \if &#1\else
4350 \@rotateUndecipherable{#1}%
4351 \fi
4352 \fi
4353 \fi
4354 \fi
4355 \fi
4356 \fi
4357 \fi
4358 \fi
4359 \fi
4360 \fi
4361 \fi
4362 \fi
4363 \fi
4364 \fi
4365 \fi
4366 \fi
4367 }
4368
4369 \newcommand\@rotateUndecipherable[1]{%
4370 % REPLACE UNDECIPHERABLE SYMBOL WITH A TOKEN CHARACTER (DEFAULT .)
4371 \expandafter\@gobble#1\undecipherable%
4372 % DONE... CLOSE UP SHOP
4373 }
4374 % \end{macrocode}
4375 % \end{macro}
4376
4377 % \begin{macrocode}
4378 \catcode`\&=4
4379 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
4380 %</package>
4381 % \end{macrocode}
4382 %
4383 % \Finale
4384 \endinput
4385 %
4386 % End of file `stringstrings.dtx'.