freepascal.compiler/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. 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}
\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}