.. index::
    single: Strings

.. _Strings:

*******
Strings
*******


  StringOps – Basic string manipulation utilities in Oberon.

  This module provides the following procedures:

  - Length:  Return the length of a string.
  - Insert:  Insert a string into another string at a given position.
  - Append:  Append a string at the end of another string.
  - Delete:  Delete characters from a string.
  - Cap:     Convert lowercase ASCII letters in a string to uppercase.
  - Replace: Replace a portion of a string with another string.

  These procedures are designed for null-terminated `ARRAY OF CHAR` strings,
  and always ensure proper 0X-termination.


Procedures
==========

.. _Strings.Length:

Length
------


    Return the number of characters in `str` up to and excluding the first 0X.

    Parameters:
      str -- The string for which the length will be returned.

    Returns:
      The length of the `str`.

    Example:
      str := "HelloWorld";
      len := Length(src);  (* len becomes 10 *)
  

.. code-block:: modula2

    PROCEDURE Length*(str: ARRAY OF CHAR): INTEGER;

.. _Strings.Insert:

Insert
------


    Insert the string `src` into `dst` at position `pos`.
    If `pos = Length(dst)`, `src` is appended to the end of `dst`.
    If the total length exceeds the available space in `dst`, the result is truncated,
    and the string is always null-terminated (with 0X).

    Parameters:
      src -- The string to insert.
      pos -- The position in `dst` at which to insert `src`. Must be in [0, Length(dst)].
      dst -- The destination string (modified in place).

    Example:
      dst := "Hello";
      Insert("World", 5, dst);  (* dst becomes "HelloWorld" *)
  

.. code-block:: modula2

    PROCEDURE Insert*(src: ARRAY OF CHAR; pos: INTEGER; VAR dst: ARRAY OF CHAR);

.. _Strings.Append:

Append
------


    Append a string at the end of another string.
    `Append(str, dst)` has the same effect as `Insert(str, Length(dst), dst)`.
    If the total length exceeds the available space in `dst`, the result is truncated,
    and the string is always null-terminated (with 0X).

    Parameters:
      str -- The string to append.
      dst -- The destination string (modified in place).

    Example:
      dst := "Hello";
      Append("World", dst);  (* dst becomes "HelloWorld" *)
  

.. code-block:: modula2

    PROCEDURE Append*(str: ARRAY OF CHAR; VAR dst: ARRAY OF CHAR);

.. _Strings.Delete:

Delete
------


    Delete `n` characters from string `str`, starting at position `pos`.
    If `n > Length(str) - pos`, the string is truncated at position `pos`.
    The result is always null-terminated.

    Parameters:
      str -- The input string (modified in place).
      pos -- The position to start deletion (must be in [0, Length(str)]).
      n   -- The number of characters to delete.

    Example:
      str := "abcdef";
      Delete(str, 2, 2);  (* str becomes "abef" *)
  

.. code-block:: modula2

    PROCEDURE Delete*(VAR str: ARRAY OF CHAR; pos, n: INTEGER);

.. _Strings.Replace:

Replace
-------


    Replace the contents of `dst` starting at position `pos` with `src`.
    This is logically equivalent to `Delete(dst, pos, Length(src))` followed by
    `Insert(src, pos, dst)`, but optimized for in-place performance.

    If the replacement exceeds available space in `dst`, the result is truncated
    to fit, and the final string is always null-terminated.

    Parameters:
      src -- The string to copy into `dst`.
      pos -- The position at which to begin replacing in `dst`.
      dst -- The destination string (modified in place).

    Example:
      dst := "HelloWorld";
      Replace("42", 5, dst);  (* dst becomes "Hello42ld" *)
  

.. code-block:: modula2

    PROCEDURE Replace*(src: ARRAY OF CHAR; pos: INTEGER; VAR dst: ARRAY OF CHAR);

.. _Strings.Extract:

Extract
-------


    Extracts (copy) a substring `dst` with `n` characters from position `pos` (`0 <= pos <= Length(src)`) in `src`.
    If `n > Length(src) - pos`, `dst` is only the part of `src` from `pos` to the end of `src`, i.e.
    `Length(src) - 1`. If the size of `dst` is not large enough to hold the result of the operation, the result
    is truncated so that `dst` is always terminated by 0X.

    Parameters:
      src -- The string to copy from.
      pos -- The position to start copying from (must be in [0, Length(str)]).
      n   -- The number of characters to copy.
      dst -- The resulting substring (modified in place).

    Example:
      Extract("HelloWorld", 0, 5, dst);  (* dst becomes "Hello" *)
  

.. code-block:: modula2

    PROCEDURE Extract*(src: ARRAY OF CHAR; pos, n: INTEGER; VAR dst: ARRAY OF CHAR);

.. _Strings.Pos:

Pos
---


    Returns the position of the first occurrence of the substring `sub` in `str`.
    Searching starts at position `pos`. If `sub` is not found, `-1` is returned.

    Parameters:
      sub -- The substring to search for,
      str -- The string to search.
      pos -- The position to start searching from (must be in [0, Length(str)]).

    Returns:
      The position of the first occurrence of the substring or `-1` if the substring is not found.

    Example:
      pos := Pos("World", "HelloWorld", 0);  (* pos becomes 5 *)
  

.. code-block:: modula2

    PROCEDURE Pos*(sub, str: ARRAY OF CHAR; pos: INTEGER): INTEGER;

.. _Strings.Cap:

Cap
---


    Convert all lowercase ASCII letters in `str` (a-z) to uppercase (A-Z).
    Other characters remain unchanged.

    Parameters:
      str -- The input string (modified in place).

    Example:
      str := "Hello World!";
      Cap(str);  (* str becomes "HELLO WORLD!" *)
  

.. code-block:: modula2

    PROCEDURE Cap*(VAR str: ARRAY OF CHAR);