Project 1: fsu::Vector::SafeIterator Upgrade

Educational Objectives: After completing this assignment, the student should be able to accomplish the following:

Background Knowledge Required: Be sure that you have mastered the material in these chapters before beginning the project:
Templates , Positional Containers , Algorithm Complexity , ADTs: Stack and Queue , Function Classes and Objects , Iterators , and Generic Algorithms .

Operational Objectives: Create two files vector_safe.h and vector_safe.cpp containing an upgrade of fsu::Vector, including the addition of the SafeIterator types and terminology support.

Deliverables: Files vector_safe.h, vector_safe.cpp, all test software f*.cpp, all test data files *.dat, makefile, and report.pdf. (Note: It is not required to have data files. For any data or tests you intend to submit, be sure your file names conform to the submit script.)

Safe Iterators There are several aspects of the usual iterator definition for vectors that one might label as "unsafe". For the following, assume: 

ContainerType           x;
ContainerType::Iterator i;  // random access iterator
size_t                  n;

  1. If a client program accesses *(i+n) (aka i[n]) for some n >= x.Size(), there is no warning.

  2. If a call is made to x.SetCapacity(k), i will be invalidated, so that it is illegal to dereference i, again an undetected error. Note that calls to x.PushBack(t) may implicitly trigger calls to SetCapacity. (Some of you ran into this insidious feature of Vector::Iterator in the COP 4530 Priority Queue assignment.)

Note that fsu::Vector has iterators defined more or less as raw pointers, which are "unsafe" as described above. On the other hand, note that fsu::Deque has "safe" iterators, in the sense that neither of the unsafe conditions occur: after a change of footprint, iterators are automatically reoriented to the new legally accessible space, and out-of-bounds dereferences are caught. (In the aforementioned Priority Queue assignment, no crashes occured for the sorted Deque implementation of ProrityQueue due to the safety of its iterators, whereas there were crashes occasioned as the 21st element was added to the sorted vector-based PriorityQueue. Why 21??)

Procedural Requirements:

  1. Copy the submit script LIB/proj1/proj1submit.sh, the appropriate fsu library container files, and appropriate test harnesses into your project directory. (Here, LIB = ~cop5517p/spring12.)

  2. Create your upgrade and test software for your upgrade.

  3. Name your upgraded container the same as the original.

  4. Name the code files as follows: 

    vector_safe.h   # contains class definitions
vector_safe.cpp # contains extra implementation code

    Note that the Vector class implementation code is in the library file vector.cpp, so the only code needed in vector_safe.cpp is that which implements the new iterators and their support mechanisms - the methods that are added to the Vector API. This is accomplished by putting the following near the bottom of your file vector_safe.h: 

      ...
  #include <vector.cpp>      # existing library file
  #include <vector_safe.cpp> # supplied in your project directory
} // namespace fsu

    Both vector.cpp and vector_safe.cpp are "slave" files to the header vector_safe.h.

  5. Turn in the upgraded software vector_safe.h, the collection of test apparatus used in testing (all files of the form f*.cpp, data files of the form *.dat, and a makefile), and a report report.pdf by executing the proj1submit.sh submit script. You might want to read the script to see what files will be picked up. DO NOT modify the script to pick up other filenames, because the receiving system (which consists of mail processing code in .procmailrc as well as a perl script project1.pl) will not recognize the new names.

    Warning: Submit scripts do not work on the program and linprog servers. Use shell.cs.fsu.edu to submit projects. If you do not receive the second confirmation with the contents of your project, there has been a malfunction.

  6. Turn in your report.pdf into Blackboard.

Technical Requirements and Specifications

  1. Upgrade the fsu container class X = fsu::Vector to include the following:
    1. Provide four iterator types: 
      X::Iterator           // "fast" iterator type
X::ConstIterator      // "fast" const iterator type
X::SafeIterator       // "safe" iterator type
X::ConstSafeIterator  // "safe" const iterator type
      Note: The existing iterator for fsu::Vector is "fast" (and unsafe), while the existing iterator for Dequeue is "safe" (and slow).
    2. Add container support for all four iterator types, using these prototype methods: 
      X::Iterator          X::Begin();
X::ConstIterator     X::Begin() const;
X::SafeIterator      X::SafeBegin();
X::ConstSafeIterator X::SafeBegin() const;
X::Iterator          X::End();
X::ConstIterator     X::End() const;
X::SafeIterator      X::SafeEnd();
X::ConstSafeIterator X::SafeEnd() const;
X::Iterator          X::rBegin();
X::ConstIterator     X::rBegin() const;
X::SafeIterator      X::SaferBegin();
X::ConstSafeIterator X::SaferBegin() const;
X::Iterator          X::rEnd();
X::ConstIterator     X::rEnd() const;
X::SafeIterator      X::SaferEnd();
X::ConstSafeIterator X::SaferEnd() const;
      The class of these iterators (random access) should be the same as the original.
    3. Provide automatic type conversion between iterator types, where appropriate, and explain why you did or did not provide it.
    4. Expand terminology support appropriately.

  2. Be sure to add the binary subtraction operator to the pointer arithmetic for all of these iterator types - so that 
    i = j - n;
    works for iterators i,j and an integer n.

  3. Name your upgraded container the same as the original, and be sure that your upgrade and associated iterators remains in the fsu namespace.

  4. The upgrade should be backward compatible (in client code) with the original container, to the extent practicable. (Where backward compatibility is not achieved, be sure to explain why in your report.)

  5. Test thoroughly.

  6. The single command "make" should compile all of your test code. All code should compile error and warning free on linprog using the command g++ -Wall -Wextra. The following: 

    HOME    = /home/courses/cop5517p/spring12
INCLUDE = -I. -I$(HOME)/cpp -I$(HOME)/tcpp 
CCO     = g++ -c -Wall -Wextra

all: fSafeIter.x fConstSafeIter.x

fSafeIter.o:  vector_safe.h fSafeIter.cpp
      $(CCO) $(INCLUDE) fSafeIter.cpp

fSafeIter.x: fSafeIter.o
      g++ -ofSafeIter.x fSafeIter.o

fConstSafeIter.o:  vector_safe.h fConstSafeIter.cpp
      $(CCO) $(INCLUDE) fConstSafeIter.cpp

fConstSafeIter.x: fConstSafeIter.o
      g++ -ofConstSafeIter.x fConstSafeIter.o

    is a sample makefile that creates executables fSafeIter.x and fConstSafeIter.x from the two files fSafeIter.cpp and vector_safe.h. Note that the order of include directories ensures that any file you have in your project directory will be used in place of a file of the same name in the course library.

  7. Describe the original and the upgrade in a report named report.pdf. Include detailed discussion of design choices made, the testing that was done, and the results of the tests. Be sure that the tests are repeatable using your submitted materials (*.cpp, *.dat, and makefile).

  8. Be sure that your report.pdf is a self-contained and self-explanatory document that can be read without access to the code sibmitted using the submit script.

Hints