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. 

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.}

\function{StrLen}{(p : PChar)}{Longint}
{
Returns the length of the null-terminated string \var{P}.
}
{None.}{\seem{Length}{}}

\input{stringex/ex1.tex}

\function{StrPCopy}{(Dest : PChar; Const Source : String)}{PChar}
{
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.
}
{No length checking is performed.}{ \seef{StrPas}}

\input{stringex/ex2.tex}

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

\input{stringex/ex3.tex}

\function {StrCopy}{(Dest,Source : PChar)}{PChar}
{ 
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.
}
{No length checking is performed.}{ \seef{StrPCopy}, \seef{StrLCopy}, \seef{StrECopy}}

\input{stringex/ex4.tex}

\function{StrLCopy}{(Dest,Source : PChar; MaxLen : Longint)}{PChar}
{
Copies \var{MaxLen} characters from \var{Source} to \var{Dest}, and makes
\var{Dest} a null terminated string. 
}
{No length checking is performed.}
{\seef{StrCopy}, \seef{StrECopy}}
 
\input{stringex/ex5.tex}

\function{StrECopy}{(Dest,Source : PChar)}{PChar}
{
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.
}
{No length checking is performed.}
{\seef{StrLCopy}, \seef{StrCopy}}

\input{stringex/ex6.tex}

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

\input{stringex/ex7.tex}

\function{StrCat}{(Dest,Source : PChar)}{PChar}
{
Attaches \var{Source} to \var{Dest} and returns \var{Dest}.
}
{No length checking is performed.}
{\seem{Concat}{}}

\input{stringex/ex11.tex}

\function{StrComp}{(S1,S2 : PChar)}{Longint}
{
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}
}
{None.}{\seef{StrLComp}, \seef{StrIComp}, \seef{StrLIComp}}

For an example, see \seef{StrLComp}.

\function{StrLComp}{(S1,S2 : PChar; L : Longint)}{Longint}
{
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}
}
{None.}{\seef{StrComp}, \seef{StrIComp}, \seef{StrLIComp}}

\input{stringex/ex8.tex}

\function{StrIComp}{(S1,S2 : PChar)}{Longint}
{
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}
}
{None.}{\seef{StrLComp}, \seef{StrComp}, \seef{StrLIComp}}

\input{stringex/ex8.tex}

\function{StrLIComp}{(S1,S2 : PChar; L : Longint)}{Longint}
{
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}
}
{None.}{\seef{StrLComp}, \seef{StrComp}, \seef{StrIComp}}

For an example, see \seef{StrIComp}

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

\input{stringex/ex10.tex}

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

\input{stringex/ex12.tex}

\function{StrScan}{(P : PChar; C : Char)}{PChar}
{
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}.
}
{None.}{\seem{Pos}{}, \seef{StrRScan}, \seef{StrPos}}

\input{stringex/ex13.tex}

\function{StrRScan}{(P : PChar; C : Char)}{PChar}
{
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}.
}
{None.}{\seem{Pos}{}, \seef{StrScan}, \seef{StrPos}}

For an example, see \seef{StrScan}.

\function{StrLower}{(P : PChar)}{PChar}
{
Converts \var{P} to an all-lowercase string. Returns \var{P}.
}
{None.}{\seem{Upcase}{}, \seef{StrUpper}}

\input{stringex/ex14.tex}

\function{StrUpper}{(P : PChar)}{PChar}
{
Converts \var{P} to an all-uppercase string. Returns \var{P}.
}
{None.}{\seem{Upcase}{}, \seef{StrLower}}

For an example, see \seef{StrLower}

\function{StrPos}{(S1,S2 : PChar)}{PChar}
{
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}.
}
{None.}{\seem{Pos}{}, \seef{StrScan}, \seef{StrRScan}}

\input{stringex/ex15.tex}

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

\input{stringex/ex16.tex}

\procedure{StrDispose}{(P : PChar)}
{
Removes the string in \var{P} from the heap and releases the memory.
}
{None.}{\seem{Dispose}{}, \seef{StrNew}}

\input{stringex/ex17.tex}

\procedure{StrAlloc}{(Len : Longint)}{PChar}
{
\var{StrAlloc} reserves memory on the heap for a string with length \var{Len},
terminating \var{\#0} included, and returns a pointer to it.
}

For an example, see \seef{StrPCopy}.