---
title: "Portable Conversions (Integers)"
number: 21
author: "[email protected] (R. S. Doiel)"
date: "2021-11-26"
copyright: "copyright (c) 2021, R. S. Doiel"
keywords: [ "Oberon", "Modules", "Types", "conversion" ]
license: "https://creativecommons.org/licenses/by-sa/4.0/"
---

Portable conversions (Integers)
===============================

By R. S. Doiel, 2021-11-26

An area in working with Oberon-07 on a POSIX machine that has proven problematic is type conversion. In particular converting to and from INTEGER or REAL and ASCII.  None of the three compilers I am exploring provide a common way of handling this. I've explored relying on C libraries but that approach has it's own set of problems.  I've become convinced a better approach is a pure Oberon-07 library that handles type conversion with a minimum of assumptions about the implementation details of the Oberon compiler or hardware. I'm calling my conversion module "Types". The name is short and descriptive and seems an appropriate name for a module consisting of type conversion tests and transformations.  My initial implementation will focusing on converting integers to and from ASCII.

INTEGER to ASCII and back again
-------------------------------

I don't want to rely on the representation of the INTEGER value in the compiler or at the machine level. That has lead me to think in terms of an INTEGER as a signed whole number.

The simplest case of converting to/from ASCII is the digits from zero to nine (inclusive). Going from an INTEGER to an ASCII CHAR is just looking up the offset of the character representing the "digit". Like wise going from ASCII CHAR to a INTEGER is a matter of mapping in the reverse direction.  Let's call these procedures `DigitToChar` and  `CharToDigit*`.

Since INTEGER can be larger than zero through nine and CHAR can hold non-digits I'm going to add two additional procedures for validating inputs -- `IsIntDigit` and `IsCharDigit`. Both return TRUE if valid, FALSE if not.

For numbers larger than one digit I can use decimal right shift to extract the ones column value or a left shift to reverse the process.  Let's called these `IntShiftRight` and `IntShiftLeft`.  For shift right it'd be good to capture the ones column being lost. For shift left it would be good to be able to shift in a desired digit. That way you could shift/unshift to retrieve to extract and put back values.

A draft definition for "Types" should look something like this.

~~~
DEFINITION Types;

(* Check if an integer is a single digit, i.e. from 0 through 9 returns
  TRUE, otherwise FALSE *)
PROCEDURE IsIntDigit(x : INTEGER) : BOOLEAN;

(* Check if a CHAR is "0" through "9" and return TRUE, otherwise FALSE *)
PROCEDURE IsCharDigit(ch : CHAR) : BOOLEAN;

(* Convert digit 0 through 9 into an ASCII CHAR "0" through "9",
  ok is TRUE if conversion successful, FALSE otherwise *)
PROCEDURE DigitToChar(x : INTEGER; VAR ch : CHAR; VAR ok : BOOLEAN);

(* Convert a CHAR "0" through "9" into a digit 0 through 9, ok
  is TRUE is conversion successful, FALSE otherwise *)
PROCEDURE CharToDigit(ch : CHAR; VAR x : INTEGER; VAR ok : BOOLEAN);

(* Shift an integer to the right (i.e. x * 0.1) set "r" to the
  value shifted out (ones column lost) and return the shifted value.
  E.g.  x becomes 12, r becomes 3.

      x := IntShiftRight(123, r);

*)
PROCEDURE IntShiftRight(x : INTEGER; VAR r : INTEGER) : INTEGER;

(* Shift an integer to the left (i.e. x * 10) adding the value y
  after the shift.

  E.g. x before 123

      x := IntShiftRight(12, 3);

*)
PROCEDURE IntShiftLeft(x, y : INTEGER) : INTEGER;

(* INTEGER to ASCII *)
PROCEDURE Itoa(src : INTEGER; VAR value : ARRAY OF CHAR; VAR ok : BOOLEAN);

(* ASCII to INTEGER *)
PROCEDURE Atoi(src : ARRAY OF CHAR; VAR value : INTEGER; VAR ok : BOOLEAN);

END Types.
~~~


NOTE: Oberon-07 provides us the ORD and CHR built as part of the
language.  These are for working with the encoding and decoding
values as integers. This is not the same thing as the meaning
of "0" versus the value of 0.  Getting to and from the encoding
to the meaning of the presentation can be done with some simple
arithmetic.

Putting it all together
-----------------------

~~~
(* DigitToChar converts an INTEGER less than to a character. E.g.
  0 should return "0", 3 returns "3", 0 returns "9" *)
PROCEDURE DigitToChar*(i : INTEGER) : CHAR;
BEGIN
 RETURN (CHR(ORD("0") + i))
END DigitToChar;

(* CharToDigit converts a single "Digit" character to an INTEGER value.
  E.g. "0" returns 0, "3" returns 3, "9" returns 9. *)
PROCEDURE CharToDigit(ch : CHAR) : INTEGER;
BEGIN
 RETURN (ORD(ch) - ORD("0"))
END CharToDigit;
~~~

This implementation is naive. It assumes the ranges of the input values
was already checked. In practice this is going to encourage bugs.

In a language like Go or Python you can return multiple values (in
Python you can return a tuple). In Oberon-07 I could use a
RECORD type to do that but that feels a little too baroque. Oberon-07
like Oberon-2, Oberon, Modula and Pascal does support "VAR" parameters.
With a slight modification to our procedure signatures I can support
easy assertions about the conversion. Let's create two functional
procedures `IsIntDigit()` and `IsCharDigit()` then update our
`DigitToChar()` and `CharToDigit()` with an a  "VAR ok : BOOLEAN"
parameter.

~~~
(* IsIntDigit returns TRUE is the integer value is zero through nine *)
PROCEDURE IsIntDigit(i : INTEGER) : BOOLEAN;
BEGIN
 RETURN ((i >= 0) & (i <= 9))
END IsIntDigit;

(* IsCharDigit returns TRUE if character is zero through nine. *)
PROCEDURE IsCharDigit(ch : CHAR) : BOOLEAN;
BEGIN
 RETURN ((ch >= "0") & (ch <= "9"))
END IsCharDigit;

(* DigitToChar converts an INTEGER less than to a character. E.g.
  0 should return "0", 3 returns "3", 0 returns "9" *)
PROCEDURE DigitToChar*(i : INTEGER; VAR ok : BOOLEAN) : CHAR;
BEGIN
 ok := IsIntDigit(i);
 RETURN (CHR(ORD("0") + i))
END DigitToChar;

(* CharToDigit converts a single "Digit" character to an INTEGER value.
  E.g. "0" returns 0, "3" returns 3, "9" returns 9. *)
PROCEDURE CharToDigit(ch : CHAR; VAR ok : BOOLEAN) : INTEGER;
BEGIN
 ok := IsCharDigit(ch);
 RETURN (ORD(ch) - ORD("0"))
END CharToDigit;
~~~

What about values are greater nine? Here we can take advantage
of our integer shift procedures.  `IntShiftRight` will move the
INTEGER value right reducing it's magnitude (i.e. x * 0.1). It
also captures the ones column lost in the shift.  Repeatedly calling
`IntShiftRight` will let us peal off the ones columns until the
value "x" is zero. `IntShiftLeft` shifts the integer to the
left meaning it raises it a magnitude (i.e. x * 10). `IntShiftLeft`
also rakes a value to shift in on the right side of the number.
In this way we can shift in a zero and get `x * 10` or shift in
another digit and get `(x * 10) + y`. This means you can use
`IntShiftRight` and recover an `IntShiftLeft`.

~~~

(* IntShiftRight converts the input integer to a real, multiplies by 0.1
  and converts by to an integer. The value in the ones column is record
  in the VAR parameter r.  E.g. IntShiftRight(123) return 12, r is set to 3. *)
PROCEDURE IntShiftRight*(x : INTEGER; VAR r : INTEGER) : INTEGER;
 VAR i : INTEGER; isNeg : BOOLEAN;
BEGIN
 isNeg := (x < 0);
 i := FLOOR(FLT(ABS(x)) * 0.1);
 r := ABS(x) - (i * 10);
 IF isNeg THEN
   i := i * (-1);
 END;
 RETURN i
END IntShiftRight;

(* IntShiftLeft multiples input value by 10 and adds y. E.g. IntShiftLeft(123, 4) return 1234 *)
PROCEDURE IntShiftLeft*(x, y : INTEGER) : INTEGER;
 VAR i : INTEGER; isNeg : BOOLEAN;
BEGIN
 isNeg := (x < 0);
 i := (ABS(x) * 10) + y;
 IF isNeg THEN
   i := i * (-1);
 END;
 RETURN i
END IntShiftLeft;

~~~

I have what I need for implementing `Itoa` (integer to ASCII).


~~~

(* Itoa converts an INTEGER to an ASCII string setting ok BOOLEAN to
  TRUE if value ARRAY OF CHAR holds the full integer, FALSE if
  value was too small to hold the integer value.  *)
PROCEDURE Itoa*(x : INTEGER; VAR value : ARRAY OF CHAR; ok : BOOLEAN);
 VAR i, j, k, l, minL : INTEGER; tmp : ARRAY BUFSIZE OF CHAR; isNeg : BOOLEAN;
BEGIN
 i := 0; j := 0; k := 0; l := LEN(value); isNeg := (x < 0);
 IF isNeg THEN
   (* minimum string length for value is 3, negative sign, digit and 0X *)
   minL := 3;
 ELSE
   (* minimum string length for value is 2, one digit and 0X *)
   minL := 2;
 END;
 ok := (l >= minL) & (LEN(value) >= LEN(tmp));
 IF ok THEN
   IF IsIntDigit(ABS(x)) THEN
     IF isNeg THEN
        value[i] := "-"; INC(i);
     END;
     value[i] := DigitToChar(ABS(x), ok); INC(i); value[i] := 0X;
   ELSE
     x := ABS(x); (* We need to work with the absolute value of x *)
     i := 0; tmp[i] := 0X;
     WHILE (x >= 10) & ok DO
       (* extract the ones columns *)
       x := IntShiftRight(x, k); (* a holds the shifted value,
                                    "k" holds the ones column
                                    value shifted out. *)
       (* write append k to our temp array holding values in
          reverse number magnitude *)
       tmp[i] := DigitToChar(k, ok); INC(i); tmp[i] := 0X;
     END;
     (* We now can convert the remaining "ones" column. *)
     tmp[i] := DigitToChar(x, ok); INC(i); tmp[i] := 0X;
     IF ok THEN
       (* now reverse the order of tmp string append each
          character to value *)
       i := 0; j := Strings.Length(tmp) - 2;
       IF isNeg THEN
         value[i] := "-"; INC(i);
       END;
       j := Strings.Length(tmp) - 1;
       WHILE (j > -1) DO
         value[i]:= tmp[j];
         INC(i); DEC(j);
         value[i] := 0X;
       END;
       value[i] := 0X;
     END;
   END;
 ELSE
   ok := FALSE;
 END;
END Itoa;

~~~

Integers in Oberon are signed. So I've chosen to capture the sign in the `isNeg` variable. This lets me work with the absolute value for the actual conversion.  One failing in this implementation is I don't detect an overflow.  Also notice that I am accumulating the individual column values in reverse order (lowest magnitude first).  That is what I need a temporary buffer. I can then copy the values in reverse order into the VAR ARRAY OF CHAR. Finally I also maintain the ok BOOLEAN to track if anything went wrong.

When moving from an ASCII representation I can simplified the code by having a local (to the module) procedure for generating magnitudes.

Going the other way I can simplify my `Atoi` if I have an local to the module "magnitude" procedure.

~~~

(* magnitude takes x and multiplies it be 10^y, If y is positive zeros
  are appended to the right side (i.e. multiplied by 10). If y is
  negative then the result is shifted left (i.e.. multiplied by
  0.1 via IntShiftRight().).  The digit(s) shift to the fractional
  side of the decimal are ignored. *)
PROCEDURE magnitude(x, y : INTEGER) : INTEGER;
 VAR z, w : INTEGER;
BEGIN
 z := 1;
 IF y >= 0 THEN
   WHILE y > 0 DO
     z := IntShiftLeft(z, 0);
     DEC(y);
   END;
 ELSE
   WHILE y < 0 DO
     x := IntShiftRight(x, w);
     INC(y);
   END;
 END;
 RETURN (x * z)
END magnitude;

~~~

And with that I can put together my `Atoi` (ASCII to integer) procedure.  I'll need to add some sanity checks as well.

~~~

(* Atoi converts an ASCII string to a signed integer value
  setting the ok BOOLEAN to TRUE on success and FALSE on error. *)
PROCEDURE Atoi*(source : ARRAY OF CHAR; VAR value : INTEGER; VAR ok : BOOLEAN);
 VAR i, l, a, m: INTEGER; isNeg : BOOLEAN;
BEGIN
 (* "i" is the current CHAR position we're analyzing, "l" is the
    length of our string, "a" holds the accumulated value,
    "m" holds the current magnitude we're working with *)
 i := 0; l := Strings.Length(source);
 a := 0; m := l - 1; isNeg := FALSE; ok := TRUE;
 (* Validate magnitude and sign behavior *)
 IF (l > 0) & (source[0] = "-") THEN
   INC(i); DEC(m);
   isNeg := TRUE;
 ELSIF (l > 0) & (source[0] = "+") THEN
   INC(i); DEC(m);
 END;

 (* The accumulator should always hold a positive integer, if the
    sign flips we have overflow, ok should be set to FALSE *)
 ok := TRUE;
 WHILE (i < l) & ok DO
   a := a + magnitude(CharToDigit(source[i], ok), m);
   IF a < 0 THEN
     ok := FALSE; (* we have an overflow condition *)
   END;
   DEC(m);
   INC(i);
 END;
 IF ok THEN
   IF (i = l) THEN
     IF isNeg THEN
       value := a * (-1);
     ELSE
       value := a;
     END;
   END;
 END;
END Atoi;

~~~

Here's an example using the procedures.

Converting an integer 1234 to an string "1234".

~~~

  x := 1234; s := ""; ok := FALSE;
  Types.Itoa(x, s, ok);
  IF ok THEN
    Out.String(s); Out.String(" = ");
    Out.Int(x,1);Out.Ln;
  ELSE
    Out.String("Something went wrong");Out.Ln;
  END;

~~~

Converting a string "56789" to integer 56789.

~~~

  x := 0; src := "56789"; ok := FALSE;
  Types.Atoi(src, x, ok);
  IF ok THEN
    Out.Int(x,1); Out.String(" = "); Out.String(s);
    Out.Ln;
  ELSE
    Out.String("Something went wrong");Out.Ln;
  END;

~~~


References and resources
------------------------

Implementations for modules for this article are linked here [Types](./Types.Mod), [TypesTest](./TypesTest.Mod) and [Tests](./Tests.Mod).

Expanded versions of the `Types` module will be available as part of Artemis Project -- [github.com/rsdoiel/Artemis](https://github.com/rsdoiel/Artemis).

Previous
--------

- [Revisiting Files](../../11/22/Revisiting-Files.html)

You are viewing proxied material from sdf.org. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.