8.2 Member Functions

The class RWFileManager adds four additional member functions to those of class RWFile. They are:

1. RWoffset allocate(RWspace s); Allocate s bytes of storage in the file, returning the offset to the start of the allocation.

2. void deallocate(RWoffset t); Deallocate (free) the storage space starting at offset t. This space must have been previously allocated by the function allocate():

3. RWOffset endData(); Return the offset to the last data in the file.

4. RWoffset start(); Return the offset from the start of the file to the first space ever allocated by RWFileManager, or return RWNIL[7] if no space has been allocated, which implies that this is a new file.

The statement:

RWoffset a = F.allocate(sizeof(double)); 

uses F of RWFileManager to allocate the space required to store an object with the size of a double, and returns the offset to that space. To write the object to the disk file, you should seek to the allocated location and use Write(). It is an error to read or write to an unallocated location in the file.

It is your responsibility to maintain a record of the offsets necessary to read the stored object. To help you do this, the first allocation ever made by an RWFileManager is considered special and can be returned by member function start() at any time. The RWFileManager will not allow you to deallocate it. This first block will typically hold information necessary to read the remaining data, perhaps the offset of a root node, or the head of a linked-list.

The following example shows the use of class RWFileManager to construct a linked-list of ints on disk. The source code is included in the toolexam subdirectory as fmgrsave.cpp and fmgrrtrv.cpp.

When using this example, you must type a carriage return after the last item you want to insert in order to guarantee that it will be added to the list. This is because different compilers handle the occurrence of an EOF on the cin stream differently.

#include <rw/filemgr.h>                                      // 1
#include <rw/rstream.h>

struct DiskNode {                                            // 2
  int       data;                                            // 3
  Rwoffset  nextNode;                                        // 4
};

main(){
   RWFileManager fm("linklist.dat");                         // 5

   // Allocate space for offset to start of the linked list:
   fm.allocate(sizeof(RWoffset));                            // 6
   // Allocate space for the first link:
   RWoffset thisNode = fm.allocate(sizeof(DiskNode));        // 7

   fm.SeekTo(fm.start());                                    // 8
   fm.Write(thisNode);                                       // 9

   DiskNode n;
   int temp;
   RWoffset lastNode;
   cout << "Input a series of integers, ";
   cout << "then EOF to end:\n";

   while (cin >> temp) {                                    // 10
     n.data = temp;
     n.nextNode = fm.allocate(sizeof(DiskNode));            // 11
     fm.SeekTo(thisNode);                                   // 12
     fm.Write(n.data);                                      // 13
     fm.Write(n.nextNode);
     lastNode = thisNode;                                   // 14
     thisNode = n.nextNode;
   }

   fm.deallocate(n.nextNode);                               // 15
   n.nextNode = RWNIL;                                      // 16
   fm.SeekTo(lastNode);
   fm.Write(n.data);                                             
   fm.Write(n.nextNode);                                         
   return 0;
}                                                           // 17

Here's a line-by-line description of the program:

Having created the linked-list on disk, how might you read it? Here is a program that reads the list and prints the stored integer field:

#include <rw/filemgr.h>
#include <rw/rstream.h>

struct DiskNode {
  int       data;
  Rwoffset  nextNode;
};

main(){
   RWFileManager fm("linklist.dat");                         // 1

   fm.SeekTo(fm.start());                                    // 2
   RWoffset next;
   fm.Read(next);                                            // 3

   DiskNode n;
   while (next != RWNIL) {                                   // 4
     fm.SeekTo(next);                                        // 5
     fm.Read(n.data);                                        // 6
     fm.Read(n.nextNode);
     cout << n.data << "\n";                                 // 7
     next = n.nextNode;                                      // 8
   }
   return 0;
}                                                            // 9

And this is a line-by-line description of the program: