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 Functions and procedures.

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