[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]