Standard procedures (The GNU Modula-2 Compiler)

### 2.4 Permanently accessible base procedures. ¶

This section describes the procedures and functions which are always visible.

#### 2.4.1 Standard procedures and functions common to PIM and ISO ¶

The following procedures are implemented and conform with Programming in Modula-2 and ISO Modula-2: `NEW`, `DISPOSE`, `INC`, `DEC`, `INCL`, `EXCL` and `HALT`. The standard functions are: `ABS`, `CAP`, `CHR`, `FLOAT`, `HIGH`, `LFLOAT`, `LTRUNC`, `MIN`, `MAX`, `ODD`, `SFLOAT`, `STRUNC` `TRUNC` and `VAL`. All these functions and procedures (except `HALT`, `NEW`, `DISPOSE` and, under non constant conditions, `LENGTH`) generate in-line code for efficiency.

    (*
       ABS - returns the positive value of i.
    *)

    PROCEDURE ABS (i: <any signed type>) : <any signed type> ;

    (*
       CAP - returns the capital of character ch providing
             ch lies within the range 'a'..'z'.  Otherwise ch
             is returned unaltered.
    *)

    PROCEDURE CAP (ch: CHAR) : CHAR ;

    (*
       CHR - converts a value of a <whole number type> into a CHAR.
             CHR(x) is shorthand for VAL(CHAR, x).
    *)

    PROCEDURE CHR (x: <whole number type>) : CHAR ;

    (*
       DISPOSE - the procedure DISPOSE is replaced by:
                 DEALLOCATE(p, TSIZE(p^)) ;
                 The user is expected to import the procedure DEALLOCATE
                 (normally found in the module, Storage.)

                 In:  a variable p: of any pointer type which has been
                      initialized by a call to NEW.
                 Out: the area of memory
                      holding p^ is returned to the system.
                      Note that the underlying procedure DEALLOCATE
                      procedure in module Storage will assign p to NIL.
    *)

    PROCEDURE DISPOSE (VAR p:<any pointer type>) ;

    (*
       DEC - can either take one or two parameters.  If supplied
             with one parameter then on the completion of the call to
             DEC, v will have its predecessor value.  If two
             parameters are supplied then the value v will have its
             n'th predecessor.  For these reasons the value of n
             must be >=0.
    *)

    PROCEDURE DEC (VAR v: <any base type>; [n: <any base type> = 1]) ;

    (*
       EXCL - excludes bit element e from a set type s.
    *)

    PROCEDURE EXCL (VAR s: <any set type>; e: <element of set type s>) ;

    (*
       FLOAT - will return a REAL number whose value is the same as o.
    *)

    PROCEDURE FLOAT (o: <any whole number type>) : REAL ;

    (*
       FLOATS - will return a SHORTREAL number whose value is the same as o.
    *)

    PROCEDURE FLOATS (o: <any whole number type>) : REAL ;

    (*
       FLOATL - will return a LONGREAL number whose value is the same as o.
    *)

    PROCEDURE FLOATL (o: <any whole number type>) : REAL ;

    (*
       HALT - will call the HALT procedure inside the module M2RTS.
              Users can replace M2RTS.
    *)

    PROCEDURE HALT ;

    (*
       HIGH - returns the last accessible index of an parameter declared as
              ARRAY OF CHAR.  Thus

              PROCEDURE foo (a: ARRAY OF CHAR) ;
              VAR
                 c: CARDINAL ;
              BEGIN
                 c := HIGH(a)
              END foo ;

              BEGIN
                 foo('hello')
              END

              will cause the local variable c to contain the value 5
    *)

    PROCEDURE HIGH (a: ARRAY OF CHAR) : CARDINAL ;

    (*
       INC - can either take one or two parameters.  If supplied
             with one parameter then on the completion of the call to
             INC, v will have its successor value.  If two
             parameters are supplied then the value v will have its
             n'th successor.  For these reasons the value of n
             must be >=0.
    *)

    PROCEDURE INC (VAR v: <any base type>; [n: <any base type> = 1]) ;

    (*
       INCL - includes bit element e to a set type s.
    *)

    PROCEDURE INCL (VAR s: <any set type>; e: <element of set type s>) ;

    (*
       LFLOAT - will return a LONGREAL number whose value is the same as o.
    *)

    PROCEDURE LFLOAT (o: <any whole number type>) : LONGREAL ;

    (*
       LTRUNC - will return a LONG<type> number whose value is the
                same as o.  PIM2, PIM3 and ISO Modula-2 will return
                a LONGCARD whereas PIM4 returns LONGINT.
    *)

    PROCEDURE LTRUNC (o: <any floating point type>) : LONG<type> ;

    (*
       MIN - returns the lowest legal value of an ordinal type.
    *)

    PROCEDURE MIN (t: <ordinal type>) : <ordinal type> ;

    (*
       MAX - returns the largest legal value of an ordinal type.
    *)

    PROCEDURE MAX (t: <ordinal type>) : <ordinal type> ;

    (*
       NEW - the procedure NEW is replaced by:
             ALLOCATE(p, TSIZE(p^)) ;
             The user is expected to import the procedure ALLOCATE
             (normally found in the module, Storage.)

             In:  a variable p: of any pointer type.
             Out: variable p is set to some allocated memory
                  which is large enough to hold all the contents of p^.
    *)

    PROCEDURE NEW (VAR p:<any pointer type>) ;

    (*
       ODD - returns TRUE if the value is not divisible by 2.
    *)

    PROCEDURE ODD (x: <whole number type>) : BOOLEAN ;

    (*
       SFLOAT - will return a SHORTREAL number whose value is the same
                as o.
    *)

    PROCEDURE SFLOAT (o: <any whole number type>) : SHORTREAL ;

    (*
       STRUNC - will return a SHORT<type> number whose value is the same
                as o.  PIM2, PIM3 and ISO Modula-2 will return a
                SHORTCARD whereas PIM4 returns SHORTINT.
    *)

    PROCEDURE STRUNC (o: <any floating point type>) : SHORT<type> ;

    (*
       TRUNC - will return a <type> number whose value is the same as o.
               PIM2, PIM3 and ISO Modula-2 will return a CARDINAL
               whereas PIM4 returns INTEGER.
    *)

    PROCEDURE TRUNC (o: <any floating point type>) : <type> ;

    (*
       TRUNCS - will return a <type> number whose value is the same
                as o.  PIM2, PIM3 and ISO Modula-2 will return a
                SHORTCARD whereas PIM4 returns SHORTINT.
    *)

    PROCEDURE TRUNCS (o: <any floating point type>) : <type> ;

    (*
       TRUNCL - will return a <type> number whose value is the same
                as o.  PIM2, PIM3 and ISO Modula-2 will return a
                LONGCARD whereas PIM4 returns LONGINT.
    *)

    PROCEDURE TRUNCL (o: <any floating point type>) : <type> ;

    (*
       VAL - converts data i of <any simple data type 2> to
             <any simple data type 1> and returns this value.
             No range checking is performed during this conversion.
    *)

    PROCEDURE VAL (<any simple data type 1>,
                   i: <any simple data type 2>) : <any simple data type 1> ;

#### 2.4.2 ISO specific standard procedures and functions ¶

The standard function `LENGTH` is specific to ISO Modula-2 and is defined as:

    (*
       IM - returns the imaginary component of a complex type.
            The return value will the same type as the imaginary field
            within the complex type.
    *)

    PROCEDURE IM (c: <any complex type>) : <floating point type> ;

    (*
       INT - returns an INTEGER value which has the same value as v.
             This function is equivalent to: VAL(INTEGER, v).
    *)

    PROCEDURE INT (v: <any ordinal type>) : INTEGER ;

    (*
       LENGTH - returns the length of string a.
    *)

    PROCEDURE LENGTH (a: ARRAY OF CHAR) : CARDINAL ;

This function is evaluated at compile time, providing that string `a` is a constant. If `a` cannot be evaluated then a call is made to `M2RTS.Length`.

    (*
       ODD - returns a BOOLEAN indicating whether the whole number
             value, v, is odd.
    *)

    PROCEDURE ODD (v: <any whole number type>) : BOOLEAN ;

    (*
       RE - returns the real component of a complex type.
            The return value will the same type as the real field
            within the complex type.
    *)

    PROCEDURE RE (c: <any complex type>) : <floating point type> ;