Documentation fixes
[vlp.git] / src / int / util.c
index 39b4087b6be077e86438b5045f07898e19ab665e..898587ddc3713799f0d232620b79d425791f836d 100644 (file)
@@ -1,4 +1,4 @@
-     /* Loglan82 Compiler&Interpreter
+/* Loglan82 Compiler&Interpreter
      Copyright (C) 1981-1993 Institute of Informatics, University of Warsaw
      Copyright (C)  1993, 1994 LITA, Pau
      
@@ -37,140 +37,179 @@ or             Andrzej Salwicki
 
 #include <time.h>
 
-/* Utility routines */
+/**
+ * @file
+ * @brief Utility routines
+ */
 
-
-word entier(x)                         /* Compute entier (floor) */
-double x;
+/**
+ * Compute entier (floor)
+ */
+word entier(double x)
 {
-    word i;
-
-    if (x >= 0.0)
-    {
-        i = (word)x;
-       return(i);
-    }
-    else
-    {
-        i = (word)(-x);
-       i = -i;
-       if ((double)i <= x) return(i);  else return(i-1);
-    }
-} /* end entier */
-
-
-word shift(x, n)                       /* shift x by n bits */
-word x, n;
+       word i;
+
+       if (x >= 0.0) {
+               i = (word)x;
+               return i;
+       } else {
+               i = (word)(-x);
+               i = -i;
+               if ((double)i <= x)
+                       return i;
+               else
+                       return i - 1;
+       }
+}
+
+/**
+ * shift x by n bits
+ */
+word shift(word x, word n)
 {
-    if (n == 0) return (x);
-    if (n > 0) return (x << n);
-    else return ( (x >> -n) & ~(~(word)0 << (8*sizeof(word)+n)) );
-} /* end shift */
+       if (n == 0)
+               return (x);
+       if (n > 0)
+               return (x << n);
+       else
+               return ((x >> -n) & ~(~(word)0 << (8 * sizeof(word) + n)));
+}
 
 
-char *asciiz(virt)                   /* Get ASCIIZ string from arrayof char */
-virtaddr *virt;
-{
-    word am;
-    int len, i;
-    char *cp;
-
-    if (member(virt, &am))
-    {
-        len = M[ am ]-3;               /* length of the string */
-        cp = ballocate(len+1);         /* allocate buffer for the string */
-       if (cp == NULL) errsignal(RTEMEMOV);
-       for (i = 0;  i < len;  i++) cp[ i ] = (char) M[ am+3+i ];
-       cp[ len ] = '\0';               /* terminate string with 0 byte */
-       return (cp);
-    }
-    else errsignal(RTEREFTN);          /* reference to none */
-} /* end asciiz */
-
-
-void addext(fname, ext)                        /* Add extension to a file name */
-char *fname, *ext;
+/**
+ * Get ASCIIZ string from arrayof char
+ */
+char *asciiz(virtaddr *virt)
 {
-    char *cp;
+       word am;
+       int len, i;
+       char *cp;
+
+       if (member(virt, &am)) {
+               /* length of the string */
+               len = M[am] - 3;
+               /* allocate buffer for the string */
+               cp = ballocate(len + 1);
+
+               if (cp == NULL)
+                       errsignal(RTEMEMOV);
+
+               for (i = 0; i < len; i++)
+                       cp[i] = (char) M[am + 3 + i];
+
+               /* terminate string with 0 byte */
+               cp[len] = '\0';
+               return cp;
+       }
+       else {
+               /* reference to none */
+               errsignal(RTEREFTN);
+       }
+}
 
-    cp = fname;
-    while (*cp != '\0' && *cp != '.') cp++;
-    strcpy(cp, ext);
-} /* end addext */
+/**
+ * Add extension to a file name
+ */
+void addext(char *fname, char *ext)
+{
+       char *cp;
 
+       cp = fname;
+       while (*cp != '\0' && *cp != '.')
+               cp++;
+       strcpy(cp, ext);
+}
 
 void usage()
 {
 }
 
-
-void abend(msg)                                /* Print error message and abort */
-char *msg;
+/**
+ * Print error message and abort
+ */
+void abend(char *msg)
 {
-    fprintf(stderr, "Error: %s\n", msg);
-    exit(8);
-} /* end abend */
+       fprintf(stderr, "Error: %s\n", msg);
+       exit(8);
+}
 
 
 /* Pseudo random number generator */
 
 static int ranpat1 = 7, ranpat2 = 503, ranpat3 = 15661;
 
-void ranset()                          /* Initialize generator */
+/**
+ * Initializes random number generator
+ */
+void ranset()
 {
-    long tim;
-
-    time(&tim);
-    ranpat1 = tim % 30269;
-    ranpat2 = tim % 30307;
-    ranpat3 = tim % 30323;
-} /* end ranset */
+       long tim;
 
+       time(&tim);
+       ranpat1 = tim % 30269;
+       ranpat2 = tim % 30307;
+       ranpat3 = tim % 30323;
+}
 
-double prandom()                               /* Produce next pseudo random number */
+/**
+ * Produces next pseudo random number
+ *
+ * @see ranset must be invoked before running this function
+ */
+double prandom()
 {
-    int i;
-    double r;
-
-    ranpat1 = 171*(ranpat1 % 177)- 2*(ranpat1 / 177);
-    if (ranpat1 < 0) ranpat1 += 30269;
-    ranpat2 = 172*(ranpat2 % 176)-35*(ranpat2 / 176);
-    if (ranpat2 < 0) ranpat2 += 30307;
-    ranpat3 = 170*(ranpat3 % 178)-63*(ranpat3 / 178);
-    if (ranpat3 < 0) ranpat3 += 30323;
-    r = ranpat1/30269.0 + ranpat2/30307.0 + ranpat3/30323.0;
-    i = (int)r;
-    return (r-i);
-}
+       int i;
+       double r;
 
+       ranpat1 = 171 * (ranpat1 % 177) - 2 * (ranpat1 / 177);
+       if (ranpat1 < 0)
+               ranpat1 += 30269;
 
-void moveblock(from, to, len)          /* Copy a block of memory */
-char *from, *to;
-word len;
-{
-    while (len-- > 0) *to++ = *from++;
-} /* end moveblock */
+       ranpat2 = 172 * (ranpat2 % 176) - 35 * (ranpat2 / 176);
 
+       if (ranpat2 < 0)
+               ranpat2 += 30307;
 
-/**************************************************************
+       ranpat3 = 170 * (ranpat3 % 178) - 63 * (ranpat3 / 178);
+
+       if (ranpat3 < 0)
+               ranpat3 += 30323;
 
-#define LINE   10
-void dump(pix, from, len)
-word pix, from;
-int len;
+       r = ranpat1 / 30269.0 + ranpat2 / 30307.0 + ranpat3 / 30323.0;
+       i = (int)r;
+       return r - i;
+}
+
+/**
+ * Copy a block of memory
+ *
+ * @param from[in] source block to copy from
+ * @param to[out] destination block to copy to
+ * @param len number of character to copy
+ */
+void moveblock(char *from, char *to, word len)
 {
-    int i;
-    memory M;
-
-    M = process[ pix ].M;
-    while (len > 0)
-    {
-       printf("%6ld: ", (long) from);
-       for (i = 0; i < LINE; i++) printf("%7ld", (long)M[from++]);
-       putchar('\n');
-       len -= LINE;
-    }
+       while (len-- > 0) {
+               *to++ = *from++;
+       }
 }
 
+/**************************************************************
+
+#define LINE 10
+void dump(word pix, word from, int len)
+{
+       int i;
+       memory M;
+
+       M = process[pix].M;
+       while (len > 0) {
+               printf("%6ld: ", (long) from);
+               for (i = 0; i < LINE; i++)
+                       printf("%7ld", (long)M[from++]);
+               putchar('\n');
+               len -= LINE;
+       }
+}
  **************************************************************/