Subsections

- 1 Functions and procedures.
  - 1 StrAlloc
  - 2 StrCat
  - 3 StrComp
  - 4 StrCopy
  - 5 StrDispose
  - 6 StrECopy
  - 7 StrEnd
  - 8 StrIComp
  - 9 StrLCat
  - 10 StrLComp
  - 11 StrLCopy
  - 12 StrLen
  - 13 StrLIComp
  - 14 StrLower
  - 15 StrMove
  - 16 StrNew
  - 17 StrPas
  - 18 StrPCopy
  - 19 StrPos
  - 20 StrRScan
  - 21 StrScan
  - 22 StrUpper

# 21 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.

# 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