Subsections

19. The STRINGS unit.

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.

19.1 Functions and procedures.


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


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


19.1.3 StrComp

Declaration
Function StrComp (S1,S2 : PChar) : Longint;

Description

Compares the null-terminated strings S1 and S2. The result is

Errors
None.
See also
StrLComp, StrIComp, StrLIComp
For an example, see StrLComp.


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


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


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


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


19.1.8 StrIComp

Declaration
Function StrIComp (S1,S2 : PChar) : Longint;

Description

Compares the null-terminated strings S1 and S2, ignoring case. The result is

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.


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


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

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.


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


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


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

Errors
None.
See also
StrLComp, StrComp, StrIComp
For an example, see StrIComp


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


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


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


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


19.1.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.1.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.


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


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


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

root
2000-12-20