DEFINITION MODULE Strings;
(* Bounded string operations over descriptor strings (classic
   Modula-2 form). Sources are [0..] indexed; destinations are
   truncated to fit (never overrun). *)

PROCEDURE Length(VAR s : ARRAY OF CHAR) : INTEGER;
(* Number of characters in s. *)

PROCEDURE Assign(VAR src, dst : ARRAY OF CHAR);
(* Copies src into dst (truncated to dst's capacity). *)

PROCEDURE Concat(VAR s1, s2 : ARRAY OF CHAR; VAR dst : ARRAY OF CHAR);
(* dst := s1 followed by s2 (truncated to fit). *)

PROCEDURE Compare(VAR s1, s2 : ARRAY OF CHAR) : INTEGER;
(* <0, 0 or >0 as s1 is less than, equal to, or greater than s2. *)

PROCEDURE Delete(VAR s : ARRAY OF CHAR; start, count : INTEGER);
(* Removes count characters from s, beginning at position start. *)

PROCEDURE Append(VAR src, dst : ARRAY OF CHAR);
(* Appends src to dst. NOTE: dst is an open array whose descriptor
   count is the logical length, so appending past it traps until the
   string model separates length from capacity. *)

PROCEDURE Copy(VAR src, dst : ARRAY OF CHAR);
(* Alias for Assign, ISO-style name. *)

PROCEDURE Equal(VAR s1, s2 : ARRAY OF CHAR) : BOOLEAN;
(* TRUE when the two strings have equal contents. *)

PROCEDURE Pos(VAR pattern, s : ARRAY OF CHAR) : INTEGER;
(* 1-based index of the leftmost occurrence of pattern in s, or 0. *)

PROCEDURE Slice(VAR s : ARRAY OF CHAR; start, stop : INTEGER;
                VAR dst : ARRAY OF CHAR);
(* dst := s[start:stop], Python-style: start/stop are 0-based and may
   be negative (counting from the end, -1 = last character); stop is
   exclusive; both clamp to [0, Length(s)]. The result is truncated to
   dst's capacity. *)

PROCEDURE Insert(VAR src, dst : ARRAY OF CHAR; pos : INTEGER);
(* Inserts src into dst at 0-based position pos (clamped), truncating
   to dst's capacity. *)

PROCEDURE Replace(VAR src, dst : ARRAY OF CHAR; pos : INTEGER);
(* Overwrites dst from 0-based position pos with src (extending if
   src runs past dst's current end). *)

PROCEDURE Capitalize(VAR s : ARRAY OF CHAR);
(* First character upper case, the rest lower case (ASCII). *)

END Strings.