[next] [prev] [prev-tail] [tail] [up]

### 22.7 PChar functions

#### Introduction

Most PChar functions are the same as their counterparts in the STRINGS unit. The following functions are the same :

1. StrCat (674) : Concatenates two PChar strings.
2. StrComp (674) : Compares two PChar strings.
3. StrCopy (675) : Copies a PChar string.
4. StrECopy (676) : Copies a PChar string and returns a pointer to the terminating null byte.
5. StrEnd (677) : Returns a pointer to the terminating null byte.
6. StrIComp (678) : Case insensitive compare of 2 PChar strings.
7. StrLCat (678) : Appends at most L characters from one PChar to another PChar.
8. StrLComp (679) : Case sensitive compare of at most L characters of 2 PChar strings.
9. StrLCopy (680) : Copies at most L characters from one PChar to another.
10. StrLen (681) : Returns the length (exclusive terminating null byte) of a PChar string.
11. StrLIComp (681) : Case insensitive compare of at most L characters of 2 PChar strings.
12. StrLower (682) : Converts a PChar to all lowercase letters.
13. StrMove (682) : Moves one PChar to another.
14. StrNew (683) : Makes a copy of a PChar on the heap, and returns a pointer to this copy.
15. StrPos (685) : Returns the position of one PChar string in another?
16. StrRScan (686) : returns a pointer to the last occurrence of on PChar string in another one.
17. StrScan (686) : returns a pointer to the first occurrence of on PChar string in another one.
18. StrUpper (687) : Converts a PChar to all uppercase letters.

The subsequent functions are different from their counterparts in STRINGS, although the same examples can be used.

#### StrAlloc

Declaration:
  Function StrAlloc(Size: cardinal): PChar;
Description:
  StrAlloc reserves memory on the heap for a string with length Len, terminating #0 included, and returns a pointer to it.

  Additionally, StrAlloc allocates 4 extra bytes to store the size of the allocated memory. Therefore this function is NOT compatible with the StrAlloc (673) function of the Strings unit.

Errors:
  None.
See also:
  StrBufSize (759), StrDispose (760), StrAlloc (673)

For an example, see StrBufSize (759).

#### StrBufSize

Declaration:
  Function StrBufSize(var Str: PChar): cardinal;
Description:
  StrBufSize returns the memory allocated for Str. This function ONLY gives the correct result if Str was allocated using StrAlloc (759).
Errors:
  If no more memory is available, a runtime error occurs.
See also:
  StrAlloc (759).StrDispose (760).

Listing: sysutex/ex46.pp

Program Example46;
{ This program demonstrates the StrBufSize function }
{$H+}
Uses sysutils;
Const S = 'Some nice string';
Var P : Pchar;
Begin
P:=StrAlloc(Length(S)+1);
StrPCopy(P,S);
Write (P, ' has length ',length(S));
Writeln (' and buffer size ',StrBufSize(P));
StrDispose(P);
End.

#### StrDispose

Declaration:
  Procedure StrDispose(var Str: PChar);
Description:
  StrDispose frees any memory allocated for Str. This function will only function correctly if Str has been allocated using StrAlloc (759) from the SYSUTILS unit.
Errors:
  If an invalid pointer is passed, or a pointer not allocated with StrAlloc, an error may occur.
See also:
  StrBufSize (759), StrAlloc (759), StrDispose (676)

For an example, see StrBufSize (759).

#### StrPCopy

Declaration:
  Function StrPCopy(Dest: PChar; Source: string): PChar;
Description:
  StrPCopy Converts the Ansistring 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 checking is performed to see whether Dest points to enough memory to contain Source.
See also:
  StrPLCopy (761), StrPCopy (684)

For an example, see StrPCopy (684).

#### StrPLCopy

Declaration:
  Function StrPLCopy(Dest: PChar; Source: string; MaxLen: cardinal): PChar;
Description:
  StrPLCopy Converts maximally MaxLen characters of the Ansistring in Source to a Null-terminated string, and copies it to Dest. Dest needs enough room to contain the characters.
Errors:
  No checking is performed to see whether Dest points to enough memory to contain L characters of Source.
Errors:
See also:
  StrPCopy (760).

#### StrPas

Declaration:
  Function StrPas(Str: PChar): string;
Description:
  Converts a null terminated string in Str to an Ansitring, and returns this string. This string is NOT truncated at 255 characters as is the
Errors:
  None.
See also:
  StrPas (684).

For an example, see StrPas (684).

[next] [prev] [prev-tail] [front] [up]