         Disk array library 1.0 beta release for C++.       

            I.  What is it?
  This library allow you to declare arrays which will
be stored on disk.  You can then access them randomly,
like it was standard C++ array. Arrays are two-dimensional
and can store elements of selected type.
  Written by Rubtsov Grigorii, 11.23.97, version 1.0 beta.
This is FREEWARE.   Can be copied and used freely.

            II. Getting started with it.
a) First you should include disk_arr.h to your program.
#include "disk_arr.h"
Headers <stdio.h>, <stdlib.h>, <string.h>
will be included automatically.

b) Second step is declaration. It is most difficult and
important step.

Disk array should be initialized when declared.
The form of declaration with initialization is:
disk_arr<a_type>  array_name(char* file_name,
                  long xsize, long ysize,
                  a_type filling_value, bool file_type=false,
                  bool range_check=false);                                      

   a_type is type of array elements, it can be char,
int, long, float, double, complex etc. User defined types are               
also good. See more information in part III.

   array_name is name of array variable (object).

   file_name is name of file where array will be stored

   xsize and ysize is array size by x and y. There is only
one limit for size:   file size cannot be larger than 2Gb

   filling_value is value which will be assigned to all
elements of array, when it is creating.   

   file_type can be either true or false. Default value is false.
false: If it is false, temporary file will be used. If file exist it
will be deleted first. Then array will be filled up with zero_value
elements. When you finish using array, file will be deleted.
It takes some time to initialize this type of array.

true: Disk file will be used. If file doesn't exist it will
be created and filled up with zero_value elements.
If file exist it will be opened, and information stored
in it will be used as initial values of array elements.
It means that when you start program, array elements will
have same values, as they have before.
If file exist it doesn't take time to initialize array.

   range_check can be true or false. Default value is false.
If range_check is false, when you want to read or write element
which is out of range (x from 0 to xsize-1, y from 0 to ysize-1)
zero_value will be returned.

If range_check is true, when you try to access element, which
is out of range program will be terminated with debug information
displayed. 

Here is several examples:
disk_arr<float> d("c:\\d.tmp",10,100, 17.17, false, true);
      d - is 10*100 float array, filled with 17.17,
array will be with range checking, in temporary file c:\d.tmp

#include <complex.h>
complex a=0.0;
disk_arr<complex> v("c:\\temp.tmp", 50, 70, a, false, false);
      v - 50*70 complex array filled with 0, without
range checking, in temporary file c:\temp.tmp

In one program you can declare as many disk arrays as you want.

c) Checking successful initialization.
After initialization you can use operator ! to check
was file successfully opened.
Usage:
       !array_name
return false if Ok, true if failed.
It is strongly recommended that you check
successful initialization before operating
with array.
Example:                                       
       #include "disk_arr.h"

       disk_arr<float> b("c:\\temp.tmp", 50, 1000, 0.0, false, true);

       main()
       {
         if(!b) abort();  /* exit program, if initialization failed */
       .....   /*  operations with array b */
       }

d) Using disk arrays.
Operations with disk arrays are very similar to operations
with standard arrays.
For example we declared array:
  disk_arr<int> f("c:\a.tmp", 100, 100, 0, false, true);
and additional variables:
  int a, b;
Then following operations can be done:
  a = f[5][59];
  b = f[99][0] + 6 + a;
  f[5][25] = a;
  f[7][90] = f[5][25];
  f[9][1] = f[5][25]*a + b - 9;
Unsupported operations:
  Following operations cannot be used for array elements:
    ++, --, +=, -=, /=, *=

                  III. More information.
a) types suitable for array elements.
Built in types such as: bool, char, int, long, float, double
can be used.
Also user defined types can be used. For example complex:

#include <complex.h>
complex zero=0.0;
disk_arr<complex> comp_arr("c:\\c.tmp",100, 100, zero, false, true);

You can declare array element structures by yourself:
I recommend you not to use classes with pointer members
as array element.

struct my_data {  // class can be used too
   int a;
   float b[3];
   char c[100];
};

my_data zero_data={0, {0.0, 0.0, 0.0}, "Zero data"};
disk_arr<my_data> my_array("c:\\m.tmp", 100, 100, zero_data, false, true);

Note: you can have problems with system stack if you use
very large structure for array element.  I recommend you
not to use structures greater then 10000 bytes. 
Type of problem and maximum element size depends of
platform, compiler, memory model, etc. 

b)  Benchmarks:
 1) float array, 4 bytes/elem. 
 Initialization 77000 elem./sec   307 Kbytes /sec 
 Writing        12000 elem./sec   48  Kbytes /sec
 Reading        11200 elem./sec   45  Kbytes /sec

 2) user defined structure,  512 bytes/elem.
 Initialization 600 elem./sec   301 Kbytes /sec
 Writing        632 elem./sec   320 Kbytes /sec
 Reading        980 elem./sec   502 Kbytes /sec

All benchmarks were done on Pentium 133, with 1.44Gb HDD.

c) Compatibility
I wrote and tested library and all examples on Borland C++ ver 5.01
for DOS. Check compatibility for your platform with disk_arr.cpp.

d) Contact me.
If you have problems, questions, ideas contact me: 
By e-mail: grigorii@rocketmail.com
By mail: Russia, 142432 Moscow region,
Chernogolovka, Tsentral'naya 22, 122, Rubtsov Grigorii.
