fpc/docs/strings.tex

%
%   $Id$
%   This file is part of the FPC documentation.
%   Copyright (C) 1997, by Michael Van Canneyt
%
%   The FPC documentation is free text; you can redistribute it and/or
%   modify it under the terms of the GNU Library General Public License as
%   published by the Free Software Foundation; either version 2 of the
%   License, or (at your option) any later version.
%
%   The FPC Documentation is distributed in the hope that it will be useful,
%   but WITHOUT ANY WARRANTY; without even the implied warranty of
%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
%   Library General Public License for more details.
%
%   You should have received a copy of the GNU Library General Public
%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
%   Boston, MA 02111-1307, USA. 
%
\chapter{The STRINGS unit.}
\label{ch:strings}
\FPCexampledir{stringex}

This chapter describes the \var{STRINGS} unit for \fpc. This unit is system
independent, and therefore works on all supported platforms.

Since the unit only provides some procedures and functions, there is
only one section, which gives the declarations of these functions, together
with an explanation. 

\section{Functions and procedures.}

\begin{function}{StrAlloc}
\Declaration
Function StrAlloc (Len : Longint) : PChar;
\Description
\var{StrAlloc} reserves memory on the heap for a string with length \var{Len},
terminating \var{\#0} included, and returns a pointer to it.
\Errors
If there is not enough memory, a run-time error occurs.
\SeeAlso
\seef{StrNew}, \seef{StrPCopy}.
\end{function}


\begin{function}{StrCat}
\Declaration
Function StrCat (Dest,Source : PChar) : PChar;
\Description
Attaches \var{Source} to \var{Dest} and returns \var{Dest}.
\Errors
No length checking is performed.
\SeeAlso
\seem{Concat}{}
\end{function}

\FPCexample{ex11}

\begin{function}{StrComp}
\Declaration
Function StrComp (S1,S2 : PChar) : Longint;
\Description
Compares the null-terminated strings \var{S1} and \var{S2}.
The result is 
\begin{itemize}
\item A negative \var{Longint} when \var{S1<S2}.
\item 0 when \var{S1=S2}.
\item A positive \var{Longint} when \var{S1>S2}.
\end{itemize}
\Errors
None.
\SeeAlso
\seef{StrLComp}, \seef{StrIComp}, \seef{StrLIComp}
\end{function}

For an example, see \seef{StrLComp}.

\begin{function}{StrCopy}
\Declaration
Function StrCopy (Dest,Source : PChar) : PChar;
\Description
Copy the null terminated string in \var{Source} to \var{Dest}, and
returns a pointer to \var{Dest}. \var{Dest} needs enough room to contain
\var{Source}, i.e. \var{StrLen(Source)+1} bytes.
\Errors
No length checking is performed.
\SeeAlso
 \seef{StrPCopy}, \seef{StrLCopy}, \seef{StrECopy}
\end{function}

\FPCexample{ex4}

\begin{procedure}{StrDispose}
\Declaration
Procedure StrDispose (P : PChar);
\Description
Removes the string in \var{P} from the heap and releases the memory.
\Errors
None.
\SeeAlso
\seem{Dispose}{}, \seef{StrNew}
\end{procedure}

\FPCexample{ex17}

\begin{function}{StrECopy}
\Declaration
Function StrECopy (Dest,Source : PChar) : PChar;
\Description
Copies the Null-terminated string in \var{Source} to \var{Dest}, and
returns a pointer to the end (i.e. the terminating Null-character) of the
copied string.
\Errors
No length checking is performed.
\SeeAlso
\seef{StrLCopy}, \seef{StrCopy}
\end{function}

\FPCexample{ex6}

\begin{function}{StrEnd}
\Declaration
Function StrEnd (P : PChar) : PChar;
\Description
Returns a pointer to the end of \var{P}. (i.e. to the terminating
null-character.
\Errors
None.
\SeeAlso
\seef{StrLen}
\end{function}

\FPCexample{ex7}

\begin{function}{StrIComp}
\Declaration
Function StrIComp (S1,S2 : PChar) : Longint;
\Description
Compares the null-terminated strings \var{S1} and \var{S2}, ignoring case.
The result is 
\begin{itemize}
\item A negative \var{Longint} when \var{S1<S2}.
\item 0 when \var{S1=S2}.
\item A positive \var{Longint} when \var{S1>S2}.
\end{itemize}
\Errors
None.
\SeeAlso
\seef{StrLComp}, \seef{StrComp}, \seef{StrLIComp}
\end{function}

\FPCexample{ex8}

\begin{function}{StrLCat}
\Declaration
Function StrLCat (Dest,Source : PChar; MaxLen : Longint) : PChar;
\Description
Adds \var{MaxLen} characters from \var{Source} to \var{Dest}, and adds a
terminating null-character. Returns \var{Dest}.
\Errors
None.
\SeeAlso
\seef{StrCat}
\end{function}

\FPCexample{ex12}

\begin{function}{StrLComp}
\Declaration
Function StrLComp (S1,S2 : PChar; L : Longint) : Longint;
\Description
Compares maximum \var{L} characters of the null-terminated strings 
\var{S1} and \var{S2}. 
The result is 
\begin{itemize}
\item A negative \var{Longint} when \var{S1<S2}.
\item 0 when \var{S1=S2}.
\item A positive \var{Longint} when \var{S1>S2}.
\end{itemize}
\Errors
None.
\SeeAlso
\seef{StrComp}, \seef{StrIComp}, \seef{StrLIComp}
\end{function}

\FPCexample{ex8}

\begin{function}{StrLCopy}
\Declaration
Function StrLCopy (Dest,Source : PChar; MaxLen : Longint) : PChar;
\Description
Copies \var{MaxLen} characters from \var{Source} to \var{Dest}, and makes
\var{Dest} a null terminated string. 
\Errors
No length checking is performed.
\SeeAlso
\seef{StrCopy}, \seef{StrECopy}
\end{function}

\FPCexample{ex5}

\begin{function}{StrLen}
\Declaration
Function StrLen (p : PChar) : Longint;
\Description
Returns the length of the null-terminated string \var{P}.
\Errors
None.
\SeeAlso
\seem{Length}{}
\end{function}

\FPCexample{ex1}

\begin{function}{StrLIComp}
\Declaration
Function StrLIComp (S1,S2 : PChar; L : Longint) : Longint;
\Description
Compares maximum \var{L} characters of the null-terminated strings \var{S1} 
and \var{S2}, ignoring case.
The result is 
\begin{itemize}
\item A negative \var{Longint} when \var{S1<S2}.
\item 0 when \var{S1=S2}.
\item A positive \var{Longint} when \var{S1>S2}.
\end{itemize}
\Errors
None.
\SeeAlso
\seef{StrLComp}, \seef{StrComp}, \seef{StrIComp}
\end{function}

For an example, see \seef{StrIComp}

\begin{function}{StrLower}
\Declaration
Function StrLower (P : PChar) : PChar;
\Description
Converts \var{P} to an all-lowercase string. Returns \var{P}.
\Errors
None.
\SeeAlso
\seem{Upcase}{}, \seef{StrUpper}
\end{function}

\FPCexample{ex14}

\begin{function}{StrMove}
\Declaration
Function StrMove (Dest,Source : PChar; MaxLen : Longint) : PChar;
\Description
Copies \var{MaxLen} characters from \var{Source} to \var{Dest}. No
terminating null-character is copied.
Returns \var {Dest}.
\Errors
None.
\SeeAlso
\seef{StrLCopy}, \seef{StrCopy}
\end{function}

\FPCexample{ex10}

\begin{function}{StrNew}
\Declaration
Function StrNew (P : PChar) : PChar;
\Description
Copies \var{P} to the Heap, and returns a pointer to the copy.
\Errors
Returns \var{Nil} if no memory was available for the copy.
\SeeAlso
\seem{New}{}, \seef{StrCopy}, \seep{StrDispose}
\end{function}

\FPCexample{ex16}

\begin{function}{StrPas}
\Declaration
Function StrPas (P : PChar) : String;
\Description
Converts a null terminated string in \var{P} to a Pascal string, and returns
this string. The string is truncated at 255 characters.
\Errors
None.
\SeeAlso
 \seef{StrPCopy}
\end{function}

\FPCexample{ex3}

\begin{function}{StrPCopy}
\Declaration
Function StrPCopy (Dest : PChar; Const Source : String) : PChar;
\Description
Converts the Pascal string in \var{Source} to a Null-terminated 
string, and copies it to \var{Dest}. \var{Dest} needs enough room to contain
the string \var{Source}, i.e. \var{Length(Source)+1} bytes.
\Errors
No length checking is performed.
\SeeAlso
 \seef{StrPas}
\end{function}

\FPCexample{ex2}

\begin{function}{StrPos}
\Declaration
Function StrPos (S1,S2 : PChar) : PChar;
\Description
Returns a pointer to the first occurrence of \var{S2} in \var{S1}.
If \var{S2} does not occur in \var{S1}, returns \var{Nil}.
\Errors
None.
\SeeAlso
\seem{Pos}{}, \seef{StrScan}, \seef{StrRScan}
\end{function}

\FPCexample{ex15}

\begin{function}{StrRScan}
\Declaration
Function StrRScan (P : PChar; C : Char) : PChar;
\Description
Returns a pointer to the last occurrence of the character \var{C} in the
null-terminated string \var{P}. If \var{C} does not occur, returns
\var{Nil}.
\Errors
None.
\SeeAlso
\seem{Pos}{}, \seef{StrScan}, \seef{StrPos}
\end{function}


For an example, see \seef{StrScan}.


\begin{function}{StrScan}
\Declaration
Function StrScan (P : PChar; C : Char) : PChar;
\Description
Returns a pointer to the first occurrence of the character \var{C} in the
null-terminated string \var{P}. If \var{C} does not occur, returns
\var{Nil}.

\Errors
None.
\SeeAlso
\seem{Pos}{}, \seef{StrRScan}, \seef{StrPos}
\end{function}

\FPCexample{ex13}

\begin{function}{StrUpper}
\Declaration
Function StrUpper (P : PChar) : PChar;
\Description
Converts \var{P} to an all-uppercase string. Returns \var{P}.
\Errors
None.
\SeeAlso
\seem{Upcase}{}, \seef{StrLower}
\end{function}

For an example, see \seef{StrLower}