Subsections
21 The STRINGS unit.
stringex
This chapter describes the STRINGS unit for Free Pascal. 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.
1 StrAlloc
-
Declaration
- Function StrAlloc (Len : Longint) : PChar;
-
Description
- StrAlloc
reserves memory on the heap for a string with length Len,
terminating #0 included, and returns a pointer to it.
-
Errors
- If there is not enough memory, a run-time error occurs.
-
See also
- StrNew, StrPCopy.
2 StrCat
-
Declaration
- Function StrCat (Dest,Source : PChar) : PChar;
-
Description
Attaches Source to Dest and returns Dest.
-
Errors
- No length checking is performed.
-
See also
- Concat ()
-
Example
Program Example11;
Uses strings;
{ Program to demonstrate the StrCat function. }
Const P1 : PChar = 'This is a PChar String.';
Var P2 : PChar;
begin
P2:=StrAlloc (StrLen(P1)*2+1);
StrMove (P2,P1,StrLen(P1)+1); { P2=P1 }
StrCat (P2,P1); { Append P2 once more }
Writeln ('P2 : ',P2);
end.
3 StrComp
-
Declaration
- Function StrComp (S1,S2 : PChar) : Longint;
-
Description
Compares the null-terminated strings S1 and S2.
The result is
- A negative Longint when S1<S2.
- 0 when S1=S2.
- A positive Longint when S1>S2.
-
Errors
- None.
-
See also
- StrLComp, StrIComp, StrLIComp
For an example, see StrLComp.
4 StrCopy
-
Declaration
- Function StrCopy (Dest,Source : PChar) : PChar;
-
Description
Copy the null terminated string in Source to Dest, and
returns a pointer to Dest. Dest needs enough room to contain
Source, i.e. StrLen(Source)+1 bytes.
-
Errors
- No length checking is performed.
-
See also
- StrPCopy, StrLCopy, StrECopy
-
Example
Program Example4;
Uses strings;
{ Program to demonstrate the StrCopy function. }
Const P : PCHar = 'This is a PCHAR string.';
var PP : PChar;
begin
PP:=StrAlloc(Strlen(P)+1);
STrCopy (PP,P);
If StrComp (PP,P)<>0 then
Writeln ('Oh-oh problems...')
else
Writeln ('All is well : PP=',PP);
end.
5 StrDispose
-
Declaration
- Procedure StrDispose (P : PChar);
-
Description
Removes the string in P from the heap and releases the memory.
-
Errors
- None.
-
See also
- Dispose () , StrNew
-
Example
Program Example17;
Uses strings;
{ Program to demonstrate the StrDispose function. }
Const P1 : PChar = 'This is a PChar string';
var P2 : PChar;
begin
Writeln ('Before StnNew : Memory available : ',MemAvail);
P2:=StrNew (P1);
Writeln ('After StrNew : Memory available : ',MemAvail);
Writeln ('P2 : ',P2);
StrDispose(P2);
Writeln ('After StrDispose : Memory available : ',MemAvail);
end.
6 StrECopy
-
Declaration
- Function StrECopy (Dest,Source : PChar) : PChar;
-
Description
Copies the Null-terminated string in Source to Dest, and
returns a pointer to the end (i.e. the terminating Null-character) of the
copied string.
-
Errors
- No length checking is performed.
-
See also
- StrLCopy, StrCopy
-
Example
Program Example6;
Uses strings;
{ Program to demonstrate the StrECopy function. }
Const P : PChar = 'This is a PCHAR string.';
Var PP : PChar;
begin
PP:=StrAlloc (StrLen(P)+1);
If Longint(StrECopy(PP,P))-Longint(PP)<>StrLen(P) then
Writeln('Something is wrong here !')
else
Writeln ('PP= ',PP);
end.
7 StrEnd
-
Declaration
- Function StrEnd (P : PChar) : PChar;
-
Description
Returns a pointer to the end of P. (i.e. to the terminating
null-character.
-
Errors
- None.
-
See also
- StrLen
-
Example
Program Example6;
Uses strings;
{ Program to demonstrate the StrEnd function. }
Const P : PChar = 'This is a PCHAR string.';
begin
If Longint(StrEnd(P))-Longint(P)<>StrLen(P) then
Writeln('Something is wrong here !')
else
Writeln ('All is well..');
end.
8 StrIComp
-
Declaration
- Function StrIComp (S1,S2 : PChar) : Longint;
-
Description
Compares the null-terminated strings S1 and S2, ignoring case.
The result is
- A negative Longint when S1<S2.
- 0 when S1=S2.
- A positive Longint when S1>S2.
-
Errors
- None.
-
See also
- StrLComp, StrComp, StrLIComp
-
Example
Program Example8;
Uses strings;
{ Program to demonstrate the StrLComp function. }
Const P1 : PChar = 'This is the first string.';
P2 : PCHar = 'This is the second string.';
Var L : Longint;
begin
Write ('P1 and P2 are ');
If StrComp (P1,P2)<>0 then write ('NOT ');
write ('equal. The first ');
L:=1;
While StrLComp(P1,P2,L)=0 do inc (L);
dec(l);
Writeln (l,' characters are the same.');
end.
9 StrLCat
-
Declaration
- Function StrLCat (Dest,Source : PChar; MaxLen : Longint) : PChar;
-
Description
Adds MaxLen characters from Source to Dest, and adds a
terminating null-character. Returns Dest.
-
Errors
- None.
-
See also
- StrCat
-
Example
Program Example12;
Uses strings;
{ Program to demonstrate the StrLCat function. }
Const P1 : PChar = '1234567890';
Var P2 : PChar;
begin
P2:=StrAlloc (StrLen(P1)*2+1);
P2^:=#0; { Zero length }
StrCat (P2,P1);
StrLCat (P2,P1,5);
Writeln ('P2 = ',P2);
end.
10 StrLComp
-
Declaration
- Function StrLComp (S1,S2 : PChar; L : Longint) : Longint;
-
Description
Compares maximum L characters of the null-terminated strings
S1 and S2.
The result is
- A negative Longint when S1<S2.
- 0 when S1=S2.
- A positive Longint when S1>S2.
-
Errors
- None.
-
See also
- StrComp, StrIComp, StrLIComp
-
Example
Program Example8;
Uses strings;
{ Program to demonstrate the StrLComp function. }
Const P1 : PChar = 'This is the first string.';
P2 : PCHar = 'This is the second string.';
Var L : Longint;
begin
Write ('P1 and P2 are ');
If StrComp (P1,P2)<>0 then write ('NOT ');
write ('equal. The first ');
L:=1;
While StrLComp(P1,P2,L)=0 do inc (L);
dec(l);
Writeln (l,' characters are the same.');
end.
11 StrLCopy
-
Declaration
- Function StrLCopy (Dest,Source : PChar; MaxLen : Longint) : PChar;
-
Description
Copies MaxLen characters from Source to Dest, and makes
Dest a null terminated string.
-
Errors
- No length checking is performed.
-
See also
- StrCopy, StrECopy
-
Example
Program Example5;
Uses strings;
{ Program to demonstrate the StrLCopy function. }
Const P : PCHar = '123456789ABCDEF';
var PP : PCHar;
begin
PP:=StrAlloc(11);
Writeln ('First 10 characters of P : ',StrLCopy (PP,P,10));
end.
12 StrLen
-
Declaration
- Function StrLen (p : PChar) : Longint;
-
Description
Returns the length of the null-terminated string P.
-
Errors
- None.
-
See also
- Length ()
-
Example
Program Example1;
Uses strings;
{ Program to demonstrate the StrLen function. }
Const P : PChar = 'This is a constant pchar string';
begin
Writeln ('P : ',p);
Writeln ('length(P) : ',StrLen(P));
end.
13 StrLIComp
-
Declaration
- Function StrLIComp (S1,S2 : PChar; L : Longint) : Longint;
-
Description
Compares maximum L characters of the null-terminated strings S1
and S2, ignoring case.
The result is
- A negative Longint when S1<S2.
- 0 when S1=S2.
- A positive Longint when S1>S2.
-
Errors
- None.
-
See also
- StrLComp, StrComp, StrIComp
For an example, see StrIComp
14 StrLower
-
Declaration
- Function StrLower (P : PChar) : PChar;
-
Description
Converts P to an all-lowercase string. Returns P.
-
Errors
- None.
-
See also
- Upcase () , StrUpper
-
Example
Program Example14;
Uses strings;
{ Program to demonstrate the StrLower and StrUpper functions. }
Const
P1 : PChar = 'THIS IS AN UPPERCASE PCHAR STRING';
P2 : PChar = 'this is a lowercase string';
begin
Writeln ('Uppercase : ',StrUpper(P2));
StrLower (P1);
Writeln ('Lowercase : ',P1);
end.
15 StrMove
-
Declaration
- Function StrMove (Dest,Source : PChar; MaxLen : Longint) : PChar;
-
Description
Copies MaxLen characters from Source to Dest. No
terminating null-character is copied.
Returns Dest.
-
Errors
- None.
-
See also
- StrLCopy, StrCopy
-
Example
Program Example10;
Uses strings;
{ Program to demonstrate the StrMove function. }
Const P1 : PCHAR = 'This is a pchar string.';
Var P2 : Pchar;
begin
P2:=StrAlloc(StrLen(P1)+1);
StrMove (P2,P1,StrLen(P1)+1); { P2:=P1 }
Writeln ('P2 = ',P2);
end.
16 StrNew
-
Declaration
- Function StrNew (P : PChar) : PChar;
-
Description
Copies P to the Heap, and returns a pointer to the copy.
-
Errors
- Returns Nil if no memory was available for the copy.
-
See also
- New () , StrCopy, StrDispose
-
Example
Program Example16;
Uses strings;
{ Program to demonstrate the StrNew function. }
Const P1 : PChar = 'This is a PChar string';
var P2 : PChar;
begin
P2:=StrNew (P1);
If P1=P2 then
writeln ('This can''t be happening...')
else
writeln ('P2 : ',P2);
end.
17 StrPas
-
Declaration
- Function StrPas (P : PChar) : String;
-
Description
Converts a null terminated string in P to a Pascal string, and returns
this string. The string is truncated at 255 characters.
-
Errors
- None.
-
See also
- StrPCopy
-
Example
Program Example3;
Uses strings;
{ Program to demonstrate the StrPas function. }
Const P : PChar = 'This is a PCHAR string';
var S : string;
begin
S:=StrPas (P);
Writeln ('S : ',S);
end.
18 StrPCopy
-
Declaration
- Function StrPCopy (Dest : PChar; Const Source : String) : PChar;
-
Description
Converts the Pascal string in Source to a Null-terminated
string, and copies it to Dest. Dest needs enough room to contain
the string Source, i.e. Length(Source)+1 bytes.
-
Errors
- No length checking is performed.
-
See also
- StrPas
-
Example
Program Example2;
Uses strings;
{ Program to demonstrate the StrPCopy function. }
Const S = 'This is a normal string.';
Var P : Pchar;
begin
p:=StrAlloc (length(S)+1);
if StrPCopy (P,S)<>P then
Writeln ('This is impossible !!')
else
writeln (P);
end.
19 StrPos
-
Declaration
- Function StrPos (S1,S2 : PChar) : PChar;
-
Description
Returns a pointer to the first occurrence of S2 in S1.
If S2 does not occur in S1, returns Nil.
-
Errors
- None.
-
See also
- Pos () , StrScan, StrRScan
-
Example
Program Example15;
Uses strings;
{ Program to demonstrate the StrPos function. }
Const P : PChar = 'This is a PChar string.';
S : Pchar = 'is';
begin
Writeln ('Position of ''is'' in P : ',longint(StrPos(P,S))-Longint(P));
end.
20 StrRScan
-
Declaration
- Function StrRScan (P : PChar; C : Char) : PChar;
-
Description
Returns a pointer to the last occurrence of the character C in the
null-terminated string P. If C does not occur, returns
Nil.
-
Errors
- None.
-
See also
- Pos () , StrScan, StrPos
For an example, see StrScan.
21 StrScan
-
Declaration
- Function StrScan (P : PChar; C : Char) : PChar;
-
Description
Returns a pointer to the first occurrence of the character C in the
null-terminated string P. If C does not occur, returns
Nil.
-
Errors
- None.
-
See also
- Pos () , StrRScan, StrPos
-
Example
Program Example13;
Uses strings;
{ Program to demonstrate the StrScan and StrRScan functions. }
Const P : PChar = 'This is a PCHAR string.';
S : Char = 's' ;
begin
Writeln ('P, starting from first ''s'' : ',StrScan(P,s));
Writeln ('P, starting from last ''s'' : ',StrRScan(P,s));
end.
22 StrUpper
-
Declaration
- Function StrUpper (P : PChar) : PChar;
-
Description
Converts P to an all-uppercase string. Returns P.
-
Errors
- None.
-
See also
- Upcase () , StrLower
For an example, see StrLower
2004-02-13