ArrayIO

ArrayIO ( Full Release )

ArrayIO 1.01 (C) Jon Ripley 2006,2007

Overview
========

BBC BASIC for Windows does not provide any built-in means of writing entire
arrays to a file and reading them back again.  The ArrayIO library overcomes
this limitation and implements the equivalent of PRINT#file%, array() and
INPUT#file%, array().

The ArrayIO library can write any array to a file and read it back again,
there are no limitations on the type of variable stored in the array, the
number of dimensions or the size of the array.  The ArrayIO library is fast
and can handle large multi-dimensional arrays in a fraction of the time
required to read or write each element separately - the usual method of
storing arrays in files.

Installation
============

To install the ArrayIO library copy the files ArrayIO.bbc and ArrayIO.txt 
into the BBC BASIC for Windows LIB directory, this should be "C:\Program 
Files\BBC BASIC for Windows\LIB" if you have installed BBC BASIC for Windows 
in the default installation directory.  If you wish to remove this library 
you should delete these two files.

Usage
=====

To make use of this library in your own programs you should add the following
line to the initialisation routine.

      INSTALL @lib$+"ArrayIO.bbc"

Interface
=========

DEF PROC_WriteArray(hfile%, parr%)
----------------------------------
PROC_WriteArray writes the contents of the array pointed to by parr% to the
file specified by hfile%.  The pointer to any array can be passed to this
routine by prefixing the array variable with the address of operator '^'.

Example usage:

      DIM array(9, 9, 9, 9)
      REM Initialise array
      hfile% = OPENOUT("data.dat")
      PROC_WriteArray(hfile%, ^array())
      CLOSE#hfile%

DEF PROC_ReadArray(hfile%, parr%)
---------------------------------
PROC_ReadArray reads data from the file specified by hfile% and stores it in
the array pointed to by parr%.  The pointer to any array can be passed to
this routine by prefixing the array variable with the address of operator
'^'.

Example usage:

      DIM array$(1000, 10)
      hfile% = OPENIN("data.dat")
      PROC_ReadArray(hfile%, ^array$())
      CLOSE#hfile%

DEF PROC_SwapMemory(addr1%, addr2%, size%)
------------------------------------------
This routine, used internally when handling string arrays, is documented here
as it may be useful.  There is no need to call this routine unless you
specifically want to make use of its features.

PROC_SwapMemory swaps the contents of two blocks of memory, addr1% is a
pointer to the first block of memory, addr2% is a pointer to the second block
of memory and size% is the number of bytes to exchange.

Credits
=======

Richard Russell for suggesting the SwapMemory function.

Change Log
==========

1.00 04aug2006 Initial release
1.01 20jan2007 Added documented routine names