home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 14 / CDACTUAL.iso / cdactual / demobin / share / program / c / XXALLOC.ZIP / XXALLOC.MAN < prev    next >
Encoding:
Text File  |  1989-12-26  |  17.4 KB  |  298 lines
  1.      XXXXXXXXAAAALLLLLLLLOOOOCCCC((((3333))))            UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((llllooooccccaaaallll))))            XXXXXXXXAAAALLLLLLLLOOOOCCCC((((3333))))
  2.      NNNNAAAAMMMMEEEE
  3.           xxalloc - family of routines for multi-dimensional dynamic
  4.           array allocation, initialization, printing, renumbering, and
  5.           freeing
  6.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  7.           ####iiiinnnncccclllluuuuddddeeee <<<<xxxxxxxxaaaalllllllloooocccc....hhhh>>>>
  8.           cccccccc [flags] files ----llllxxxxxxxxaaaalllllllloooocccc [[[[----llllxxxxxxxxeeeerrrrrrrroooorrrr]]]] [libraries]
  9.           BBBBaaaasssseeee RRRRoooouuuuttttiiiinnnneeeessss
  10.           void xx_error(s) char *s;
  11.           char *xx_alloc(n) unsigned n;
  12.           void xx_free(p, n) char *p; unsigned n;
  13.           long xx_amount()
  14.           PPPPrrrreeeeffffiiiixxxxeeeessss aaaannnndddd AAAArrrrgggguuuummmmeeeennnnttttssss
  15.           {type} - char - short - long - int - float - double
  16.           {*} - * - ** - *** for 1 - 2 - 3 dimensions
  17.           {t} - c - s - l - i - f - d
  18.           {d} - 1 - 2 - 3
  19.           {args} - ib,ie - ib,ie,jb,je - ib,ie,jb,je,kb,ke
  20.           FFFFuuuunnnnccccttttiiiioooonnnnssss ffffoooorrrr SSSSiiiimmmmpppplllleeee TTTTyyyyppppeeeessss
  21.           {type} {*}{t}{d}_alloc({args})
  22.           int {args};
  23.           void {t}{d}_init(m, {args}, ini)
  24.           {type} {*}m;
  25.           int {args};
  26.           {type} ini;
  27.           void {t}{d}_prnt(fp, fmt, m, {args})
  28.           FILE *fp;
  29.           char *fmt;
  30.           {type} {*}m;
  31.           int {args};
  32.           {type} {*}{t}{d}_renum(m, {args}, {args})
  33.           {type} {*}m;
  34.           int {args}, {args};
  35.           void {t}{d}_free(m, {args})
  36.           {type} {*}m;
  37.           int {args};
  38.      Page 1                                         (printed 12/26/89)
  39.      XXXXXXXXAAAALLLLLLLLOOOOCCCC((((3333))))            UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((llllooooccccaaaallll))))            XXXXXXXXAAAALLLLLLLLOOOOCCCC((((3333))))
  40.           FFFFuuuunnnnccccttttiiiioooonnnnssss ffffoooorrrr SSSSttttrrrruuuuccccttttuuuurrrreeeessss
  41.           char {*}n{d}_alloc({args}, n)
  42.           int {args}, n;
  43.           void n{d}_init(m, {args}, n, nini)
  44.           char {*}m;
  45.           int {args}, n;
  46.           void (*nini)();
  47.           void n{d}_prnt(fp, nprn, m, {args}, n)
  48.           FILE *fp;
  49.           void (*nprn)();
  50.           char {*}m;
  51.           int {args}, n;
  52.           char {*}n{d}_renum(m, {args}, {args}, n)
  53.           char {*}m;
  54.           int {args}, {args}, n;
  55.           void n{d}_free(m, {args}, n)
  56.           char {*}m;
  57.           int {args}, n;
  58.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  59.           xxalloc is a family of routines for dynamic array
  60.           manipulation in one, two and three dimensions.  Routines are
  61.           included for allocation, initialization, printing,
  62.           renumbering, and freeing both arrays of structures and
  63.           arrays of simple types.  Since the "edge-vector" approach is
  64.           used for two and three dimensional arrays, this set of
  65.           routines allows for the development of reusable subroutine
  66.           libraries without regard to some "maximum" dimension.  Both
  67.           positive and negative indices are allowed.  In this document
  68.           "array of" is often used where "pointer to" would be more
  69.           correct.
  70.           BBBBaaaasssseeee RRRRoooouuuuttttiiiinnnneeeessss
  71.           xx_error
  72.                The required error handling routine. The default
  73.                routine exits when called, but it may be replaced by a
  74.                user's routine of the same name.  The default routine
  75.                may be linked in by
  76.                cccccccc [flags] files ----llllxxxxxxxxaaaalllllllloooocccc ----llllxxxxxxxxeeeerrrrrrrroooorrrr [libraries]
  77.                The default routine is simply
  78.                #include <stdio.h>
  79.                void xx_error(s)
  80.      Page 2                                         (printed 12/26/89)
  81.      XXXXXXXXAAAALLLLLLLLOOOOCCCC((((3333))))            UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((llllooooccccaaaallll))))            XXXXXXXXAAAALLLLLLLLOOOOCCCC((((3333))))
  82.                char *s;
  83.                {
  84.                     fprintf(stderr, s);
  85.                     exit(2);
  86.                     return;
  87.                }
  88.           xx_alloc
  89.                Allocates memory and checks for error return.  Similar
  90.                to malloc().  Returns a NULL pointer if there is no
  91.                available memory or another error occurs.
  92.           xx_free
  93.                Free memory allocated with xx_alloc(). Similar to
  94.                free() but take an extra argument for the amount of
  95.                memory.
  96.           xx_amount
  97.                Returns the amount of memory currently allocated with
  98.                this package.
  99.           TTTThhhheeee ssssuuuuffffffffiiiixxxx oooonnnn tttthhhheeee ffffuuuunnnnccccttttiiiioooonnnn nnnnaaaammmmeeee iiiinnnnddddiiiiccccaaaatttteeeessss iiiittttssss ffffuuuunnnnccccttttiiiioooonnnn....  TTTThhhheeee
  100.           ffffiiiivvvveeee ffffuuuunnnnccccttttiiiioooonnnn ttttyyyyppppeeeessss aaaarrrreeee
  101.           _alloc
  102.                Allocate memory.  Returns an appropriate NULL pointer
  103.                if there is no available memory or another error
  104.                occurs.
  105.           _init
  106.                Initialize.
  107.           _prnt
  108.                Print.
  109.           _renum
  110.                Renumber the array indices.
  111.           _free
  112.                Free the allocated memory.
  113.           TTTThhhheeee pppprrrreeeeffffiiiixxxx oooonnnn tttthhhheeee ffffuuuunnnnccccttttiiiioooonnnn nnnnaaaammmmeeee iiiinnnnddddiiiiccccaaaatttteeeessss iiiittttssss ttttyyyyppppeeee.... TTTThhhheeeeyyyy aaaarrrreeee
  114.           {type}
  115.                The data type the function manipulates.
  116.                char - array of structure
  117.                char - array of char
  118.                short - array of short
  119.                long - array of long
  120.                int - array of int
  121.                float - array of float
  122.      Page 3                                         (printed 12/26/89)
  123.      XXXXXXXXAAAALLLLLLLLOOOOCCCC((((3333))))            UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((llllooooccccaaaallll))))            XXXXXXXXAAAALLLLLLLLOOOOCCCC((((3333))))
  124.                double - array of double
  125.           {*}  Number of dimensions
  126.                * - 1 dimension - pointer to
  127.                ** - 2 dimensions - pointer to pointer to
  128.                *** - 3 dimensions - pointer to pointer to pointer to
  129.           {t}  The type that the function manipulates.
  130.                n - array of structure
  131.                c - array of char
  132.                s - array of short
  133.                l - array of long
  134.                i - array of int
  135.                f - array of float
  136.                d - array of double
  137.           {d}  The dimension of the array to be manipulated.
  138.                1 - one dimension
  139.                2 - two dimensions
  140.                3 - three dimensions
  141.           AAAArrrrgggguuuummmmeeeennnnttttssss ccccoooommmmmmmmoooonnnn ttttoooo bbbbooootttthhhh ffffuuuunnnnccccttttiiiioooonnnnssss tttthhhhaaaatttt ooooppppeeeerrrraaaatttteeee oooonnnn ssssiiiimmmmpppplllleeee
  142.           ttttyyyyppppeeeessss aaaannnndddd ssssttttrrrruuuuccccttttuuuurrrreeeessss....
  143.           {args}
  144.                Integer arguments specifying the beginning and ending
  145.                indices of each dimension of the array.  For example
  146.                the length of an array with ib = -2 and ie = 5 would be
  147.                ((5 - (-2)) + 1).
  148.                ib, ie - row indices
  149.                ib, ie, jb, je - row and column indices
  150.                ib, ie, jb, je, kb, ke - row, column, and third
  151.                dimension indices
  152.           fp   FILE pointer for the printing functions' output.
  153.           AAAArrrrgggguuuummmmeeeennnnttttssss ttttoooo ffffuuuunnnnccccttttiiiioooonnnnssss tttthhhhaaaatttt ooooppppeeeerrrraaaatttteeee oooonnnn ssssiiiimmmmpppplllleeee ttttyyyyppppeeeessss....
  154.           ini  Value to initialize the array to.  Must be of {type}.
  155.           fmt  Character string to be passed as an argument to
  156.                fprintf.  It should contain the conversion
  157.                specification for a single argument of {type}.
  158.           AAAArrrrgggguuuummmmeeeennnnttttssss ttttoooo ffffuuuunnnnccccttttiiiioooonnnnssss tttthhhhaaaatttt ooooppppeeeerrrraaaatttteeee oooonnnn ssssttttrrrruuuuccccttttuuuurrrreeeessss....
  159.           n    sizeof the structure.
  160.      Page 4                                         (printed 12/26/89)
  161.      XXXXXXXXAAAALLLLLLLLOOOOCCCC((((3333))))            UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((llllooooccccaaaallll))))            XXXXXXXXAAAALLLLLLLLOOOOCCCC((((3333))))
  162.           nini Pointer to a function used to initialize the structure.
  163.                The function receives a pointer to the structure as the
  164.                only argument as shown.
  165.                void initialize_some_structure(some_struct)
  166.                struct *some_struct;
  167.           nprn Pointer to a function used to print the structure.  The
  168.                function receives a FILE pointer and a pointer to the
  169.                structure as arguments as shown.  An example is given
  170.                in the examples section.
  171.                void print_some_structure(fp, some_struct)
  172.                FILE *fp;
  173.                struct *some_struct;
  174.      EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  175.           EEEExxxxaaaammmmpppplllleeee1111 ---- OOOOppppeeeerrrraaaattttiiiioooonnnnssss oooonnnn aaaa ttttwwwwoooo ddddiiiimmmmeeeennnnssssiiiioooonnnnaaaallll aaaarrrrrrrraaaayyyy ooooffff ddddoooouuuubbbblllleeeessss
  176.           /* example1.c */
  177.           #include <stdio.h>
  178.           #include <xxalloc.h>
  179.           void mtxtsp(a, ib, ie, jb, je, b)
  180.           double **a, **b;
  181.           int ib, ie, jb, je;
  182.           {
  183.                int i, j;
  184.                double tmp;
  185.                for (i = ib; i <= ie; i++)
  186.                     for (j = i; j <= je; j++)
  187.                     {
  188.                          tmp = a[i][j];
  189.                          b[i][j] = a[j][i];
  190.                          b[j][i] = tmp;
  191.                     }
  192.                return;
  193.           }
  194.           main()
  195.           {
  196.                double **a;
  197.                int i, j;
  198.           /* allocate a two dimensional array of doubles */
  199.                a = d2_alloc(0, 9, 0, 9);
  200.           /* initialize the array to 1.0 and print */
  201.      Page 5                                         (printed 12/26/89)
  202.      XXXXXXXXAAAALLLLLLLLOOOOCCCC((((3333))))            UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((llllooooccccaaaallll))))            XXXXXXXXAAAALLLLLLLLOOOOCCCC((((3333))))
  203.                d2_init(a, 0, 9, 0, 9, 1.0);
  204.                printf(" nitialized to 1 );
  205.                d2_prnt(stdout, "%5.0f ", a, 0, 9, 0, 9);
  206.           /* set the array equal to the 2*i + j and print */
  207.                for (i = 0; i < 10; i++)
  208.                     for (j = 0; j < 10; j++)
  209.                          a[i][j] = (double) (2*i + j);
  210.                printf(" *i + j );
  211.                d2_prnt(stdout, "%5.0f ", a, 0, 9, 0, 9);
  212.           /* take the transpose and print*/
  213.                mtxtsp(a, 0, 9, 0, 9, a);
  214.                printf(" ransposed );
  215.                d2_prnt(stdout, "%5.0f ", a, 0, 9, 0, 9);
  216.           /* renumber the indices a la FORTRAN and print */
  217.           /* the new indices must be used from now on */
  218.                a = d2_renum(a, 0, 9, 0, 9, 1, 10, 1, 10);
  219.                printf(" enumbered );
  220.                d2_prnt(stdout, "%5.0f ", a, 1, 10, 1, 10);
  221.           /* renumber the indices a la C and print */
  222.           /* the new indices must be used from now on */
  223.                a = d2_renum(a, 1, 10, 1, 10, 0, 9, 0, 9);
  224.                printf(" enumbered again );
  225.                d2_prnt(stdout, "%5.0f ", a, 0, 9, 0, 9);
  226.           /* free the allocated memory */
  227.                d2_free(a, 0, 9, 0, 9);
  228.                exit(0);
  229.           }
  230.           EEEExxxxaaaammmmpppplllleeee 2222 ---- OOOOppppeeeerrrraaaattttiiiioooonnnnssss oooonnnn aaaannnn aaaarrrrrrrraaaayyyy ooooffff ssssttttrrrruuuuccccttttuuuurrrreeeessss
  231.           /* example2.c */
  232.           #include <stdio.h>
  233.           #include <xxalloc.h>
  234.           typedef struct
  235.           {
  236.                double dnum;
  237.                int inum;
  238.           } NUM;
  239.           /* structure initialization function */
  240.      Page 6                                         (printed 12/26/89)
  241.      XXXXXXXXAAAALLLLLLLLOOOOCCCC((((3333))))            UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((llllooooccccaaaallll))))            XXXXXXXXAAAALLLLLLLLOOOOCCCC((((3333))))
  242.           /* passed as an argument to {d}n_init() */
  243.           void num_init(num)
  244.           NUM *num;
  245.           {
  246.                num->dnum = 1.0;
  247.                num->inum = 1;
  248.                return;
  249.           }
  250.           /* structure printing function */
  251.           /* passed as an argument to {d}n_prnt() */
  252.           void num_prnt(fp, num)
  253.           FILE *fp;
  254.           NUM *num;
  255.           {
  256.                fprintf(fp, "%5.1f %3d ", num->dnum, num->inum);
  257.                return;
  258.           }
  259.           main()
  260.           {
  261.                int i;
  262.                NUM *num;
  263.           /* allocate a one dimensional array of NUM */
  264.                num = (NUM *) n1_alloc(0, 4, sizeof(NUM));
  265.           /* initialize the array to 1.0 and print */
  266.                n1_init(num, 0, 4, sizeof(NUM), num_init);
  267.                printf(" nitialized to 1 );
  268.                n1_prnt(stdout, num_prnt, num, 0, 4, sizeof(NUM));
  269.           /* set the array equal to the i and print */
  270.                for (i = 0; i <= 4; i++)
  271.                {
  272.                     num[i].dnum = (double) i;
  273.                     num[i].inum = i;
  274.                }
  275.                printf(" et to i );
  276.                n1_prnt(stdout, num_prnt, num, 0, 4, sizeof(NUM));
  277.           /* renumber the indices a la FORTRAN and print */
  278.           /* the new indices must be used from now on */
  279.                num = (NUM *) n1_renum(num, 0, 4, 1, 5, sizeof(NUM));
  280.                printf(" ndices renumbered );
  281.                n1_prnt(stdout, num_prnt, num, 1, 5, sizeof(NUM));
  282.                printf(" );
  283.      Page 7                                         (printed 12/26/89)
  284.      XXXXXXXXAAAALLLLLLLLOOOOCCCC((((3333))))            UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((llllooooccccaaaallll))))            XXXXXXXXAAAALLLLLLLLOOOOCCCC((((3333))))
  285.           /* free the allocated memory */
  286.                n1_free(num, 1, 5, sizeof(NUM));
  287.                exit(0);
  288.           }
  289.      FFFFIIIILLLLEEEESSSS
  290.           /lib/xxalloc.a
  291.           /lib/xxerror.a
  292.      BBBBUUUUGGGGSSSS
  293.           There is only minimal error checking and no error checking
  294.           at all between function calls.
  295.      AAAAUUUUTTTTHHHHOOOORRRR
  296.           Harold G. Walters
  297.      Page 8                                         (printed 12/26/89)
  298.