clqr-strings.tex

% Copyright (C) 2008, 2010 Bert Burgemeister
%
% Permission is granted to copy, distribute and/or modify this
% document under the terms of the GNU Free Documentation License,
% Version 1.2 or any later version published by the Free Software
% Foundation; with no Invariant Sections, no Front-Cover Texts and
% no Back-Cover Texts. For details see file COPYING.
%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Strings} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Strings can as well be manipulated by array and sequence functions;
see pages \pageref{section:Arrays} and \pageref{section:Sequences}.

\begin{LIST}{1cm}


  \IT{\arrGOO{(\FU*{STRINGP} \VAR{ foo})\\
      (\FU*{SIMPLE-STRING-P} \VAR{ foo})}{.}}
  {
    \retval{\T} if \VAR{foo} is of indicated type.
  }

  \IT{(\xorGOO{\FU*{STRING=}\\\FU*{STRING-EQUAL}}{\}} \VAR{foo}
    \VAR{bar} 
    \orGOO{\kwd{:start1} \VAR{ start-foo}\DF{\LIT{0}}\\
      \kwd{:start2} \VAR{ start-bar}\DF{\LIT{0}}\\
      \kwd{:end1} \VAR{ end-foo}\DF{\NIL}\\
      \kwd{:end2} \VAR{ end-bar}\DF{\NIL}}{\}})}
  {
    Return \retval{\T} if subsequences of \VAR{foo} and \VAR{bar} are
    equal.  Obey/ignore, respectively, case.
  }

  \IT{(\xorGOO{%
      \FU{STRING}\Goo{\kwd{/= }\XOR\kwd{-NOT-EQUAL}}\\
      \FU{STRING}\Goo{\kwd{\boldmath$>$ }\XOR\kwd{-GREATERP}}\\
      \FU{STRING}\Goo{\kwd{\boldmath$>$= }\XOR\kwd{-NOT-LESSP}}\\
      \FU{STRING}\Goo{\kwd{\boldmath$<$ }\XOR\kwd{-LESSP}}\\
      \FU{STRING}\Goo{\kwd{\boldmath$<$= }\XOR\kwd{-NOT-GREATERP}}}{\}}
    \VAR{foo} \VAR{bar}
    \orGOO{\kwd{:start1} \VAR{ start-foo}\DF{\LIT{0}}\\
      \kwd{:start2} \VAR{ start-bar}\DF{\LIT{0}}\\
      \kwd{:end1} \VAR{ end-foo}\DF{\NIL}\\
      \kwd{:end2} \VAR{ end-bar}\DF{\NIL}}{\}})}
  {\index{STRING/=}\index{STRING-NOT-EQUAL}%
    \index{STRING>@STRING$>$}\index{STRING-GREATERP}%
    \index{STRING>=@STRING$>$=}\index{STRING-NOT-LESSP}%
    \index{STRING<@STRING$<$}\index{STRING-LESSP}%
    \index{STRING<=@STRING$<$=}\index{STRING-NOT-GREATERP}%
    If \VAR{foo} is lexicographically not equal, greater, not less,
    less, or not greater, respectively, then return \retval{position}
    of first mismatching character in \VAR{foo}.  Otherwise return
    \retval{\NIL}.  Obey/ignore, respectively, case.
  }

  \IT{(\FU*{MAKE-STRING} \VAR{size} \orGOO{\kwd{:initial-element} \VAR{ char}\\
      \kwd{:element-type} \VAR{ type}\DF{\kwd{character}}}{\}})}
  {
  Return \retval{string} of length \VAR{size}.
  }

  \IT{\arrGOO{%
      (\FU*{STRING} \VAR{ x})\\
      (\xorGOO{%
        \FU*{STRING-CAPITALIZE}\\
        \FU*{STRING-UPCASE}\\
        \FU*{STRING-DOWNCASE}}{\}}
      \VAR{ x }  
      \orGOO{\kwd{:start} \VAR{ start}\DF{\LIT{0}}\\
        \kwd{:end} \VAR{ end}\DF{\NIL}}{\}})}{.}}
  {
    Convert \VAR{x} (\kwd{symbol}, \kwd{string}, or \kwd{character})
    into a \retval{string}, a \retval{string with capitalized words},
    an \retval{all-uppercase string}, or an \retval{all-lowercase
      string}, respectively.
  }

  \IT{(\xorGOO{%
      \FU*{NSTRING-CAPITALIZE}\\
      \FU*{NSTRING-UPCASE}\\
      \FU*{NSTRING-DOWNCASE}}{\}}
    \VAR{\DES{string}}  
    \orGOO{\kwd{:start} \VAR{ start}\DF{\LIT{0}}\\
      \kwd{:end} \VAR{ end}\DF{\NIL}}{\}})}
  {
    Convert \VAR{string} into a \retval{string with capitalized
      words}, an \retval{all-uppercase string}, or an
    \retval{all-lowercase string}, respectively. 
  }

  \IT{(\xorGOO{\FU*{STRING-TRIM}\\
      \FU*{STRING-LEFT-TRIM}\\
      \FU*{STRING-RIGHT-TRIM}}{\}} \VAR{char-bag} \VAR{string})}
  {
    Return \retval{\VAR{string}} with all characters in sequence
    \VAR{char-bag} removed from both ends, from the beginning, or from
    the end, respectively. 
  }

  \IT{\arrGOO{(\FU*{CHAR} \VAR{ string} \VAR{ i})\\
      (\FU*{SCHAR} \VAR{ string} \VAR{ i})}{.}}
  {
    Return zero-indexed \retval{\VAR{i}th character} of string
    ignoring/obeying, respectively, fill pointer. \kwd{setf}able.
  }

  \IT{(\FU*{PARSE-INTEGER} \VAR{string}
    \orGOO{\kwd{:start} \VAR{ start}\DF{\LIT{0}}\\
      \kwd{:end} \VAR{ end}\DF{\NIL}\\
      \kwd{:radix} \VAR{ int}\DF{\LIT{10}}\\
      \kwd{:junk-allowed} \VAR{ bool}\DF{\NIL}}{\}})}
  {
    Return \retval{integer} parsed from \VAR{string} and
    \retvalii{index} of parse end.
  }

\end{LIST}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "clqr"
%%% End: