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.}
This chapter describes the \var{STRINGS} unit for 
\fpc. 
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}
\latex{\lstinputlisting{stringex/ex11.pp}}
\html{\input{stringex/ex11.tex}}
\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}
\latex{\lstinputlisting{stringex/ex4.pp}}
\html{\input{stringex/ex4.tex}}
\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}
\latex{\lstinputlisting{stringex/ex17.pp}}
\html{\input{stringex/ex17.tex}}
\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}
\latex{\lstinputlisting{stringex/ex6.pp}}
\html{\input{stringex/ex6.tex}}
\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}
\latex{\lstinputlisting{stringex/ex7.pp}}
\html{\input{stringex/ex7.tex}}
\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}
\latex{\lstinputlisting{stringex/ex8.pp}}
\html{\input{stringex/ex8.tex}}
\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}
\latex{\lstinputlisting{stringex/ex12.pp}}
\html{\input{stringex/ex12.tex}}
\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}
\latex{\lstinputlisting{stringex/ex8.pp}}
\html{\input{stringex/ex8.tex}}
\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}
 
\latex{\lstinputlisting{stringex/ex5.pp}}
\html{\input{stringex/ex5.tex}}
\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}
\latex{\lstinputlisting{stringex/ex1.pp}}
\html{\input{stringex/ex1.tex}}
\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}
\latex{\lstinputlisting{stringex/ex14.pp}}
\html{\input{stringex/ex14.tex}}
\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}
\latex{\lstinputlisting{stringex/ex10.pp}}
\html{\input{stringex/ex10.tex}}
\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}
\latex{\lstinputlisting{stringex/ex16.pp}}
\html{\input{stringex/ex16.tex}}
\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}
\latex{\lstinputlisting{stringex/ex3.pp}}
\html{\input{stringex/ex3.tex}}
\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}
\latex{\lstinputlisting{stringex/ex2.pp}}
\html{\input{stringex/ex2.tex}}
\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}
\latex{\lstinputlisting{stringex/ex15.pp}}
\html{\input{stringex/ex15.tex}}
\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}
\latex{\lstinputlisting{stringex/ex13.pp}}
\html{\input{stringex/ex13.tex}}
\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}