DEFINITION MODULE CStr;
(* Explicit C string types and conversions.

   CString is a pointer to a NUL-terminated C byte string.  It is an
   ADDRESS alias, so it can be stored, compared with NIL, returned from
   a FOR "C" procedure, and passed to another C function without any
   hidden descriptor conversion.

   CBuffer is the same representation, used for a writable C buffer.
   A V3 ARRAY OF CHAR can still be passed directly to a C function;
   use Copy for the reverse direction (C string -> V3 string). *)

FROM SYSTEM IMPORT ADDRESS;

TYPE
  CString = ADDRESS;
  CBuffer = ADDRESS;

PROCEDURE Length (s : CString) : CARDINAL;
(* strlen-like length; NIL has length 0. *)

PROCEDURE Copy (s : CString; VAR dst : ARRAY OF CHAR) : CARDINAL;
(* Copy s into dst, truncating to dst's capacity and NUL-terminating.
   NIL clears dst.  Returns the number of bytes copied. *)

PROCEDURE IsNil (s : CString) : BOOLEAN;
(* TRUE for a NIL C string. *)

END CStr.