CS 305 -- Software Engineering

User Documentation

Version: 1.1, April 23, 1998

Maintained by: Jennifer Wasserstrass

Other Team Members: John Duggins, Tom Walcott

Changes from Previous Versions: No previous versions.

Non Standard Terminology: CS, Wasserstrass, Duggins, Walcott, StringNode, IntNode, int, prev, runtime, beloit, edu

Document Purpose: This document is a reference for both students and instructors using the program "C++ Pointers". For novice programmers the user documentation provides step-by-step instructions and information about pointers and linked lists in C++, while the detailed Help menu allows the more experienced programmer to get acquainted with the product without wading through the extra background information. Instructors will find the sections on creating lessons particularly useful.

0. Table of Contents

1. Introduction
2. Detailed Help Menu
3. Using C++ Pointers

1. Introduction to C++ Pointers

The program "C++ Pointers" aids students learning to use pointers in C++ and can be used as an instructional tool for classroom demonstrations. "C++ Pointers" uses graphical representations of the pointers and nodes that make up singly linked lists, doubly linked lists, and binary trees. After selecting one of these data structure types, the user must either enter syntactically correct C++ code into the command line or execute a loop by entering code into a separate window. Each time the user enters a new command, the display updates accordingly, demonstrating the effect of the command on the data structure.The program detects syntactic and semantic errors and alerts the user when they occur. Each command entered during a session is stored and, if the user desires, can be displayed at all times. This list, when printed out, can be used for grading purposes, or the user can include the code in a program.

A set of lessons is available for students to use, and additional lessons can be constructed. Lessons usually provide an initial data structure with instructions asking the student to alter the structure in a specific manner. In a future version of "C++ Pointers" the student will have the option to check their work for correctness while running a lesson.

2. Detailed Help Menu

Below is the menu that appears when you select the "User Manual..." option in the "Help" menu.

Introduction to "C++ Pointers"

Choosing a Node Type

Entering Commands
Commands Supported by "C++ Pointers"

Adding a Node
Deleting a Node
Assigning Data to a Node
Pointer Redirection and Assignment
Memory Leaks

If Statements
Viewing the Commands Log
Printing the Commands Log
Clearing the Screen

Running a For Loop
Running a While Loop
Stepping Through a Loop

Running a Lesson
Opening a Lesson
Starting a Lesson Over
Quitting a Lesson
Creating a Lesson
Saving a Lesson
ÝChecking a Lesson
Lesson Instructions

3. Using "C++ Pointers"

3.1. Getting Started

When "C++ Pointers" starts, four gray boxes labeled p, q, r, and s are displayed on the far left side of the work area. These boxes represent variables defined as pointers to a specific node type . You have the option to choose a node type at the beginning of a session or use the default type.

The nodes are represented by rectangles with adjacent pointer boxes. New nodes are completely grayed out, as are uninitialized pointer boxes. When data is assigned to a node, this data appears in the data field of the node. When a pointer is assigned the value NULL, the pointer box becomes a white box with a diagonal line. Lines coming out of the pointer boxes represent links between nodes.

The "Show Key" option under the "Help" menu brings up a key (like the picture above) that explains what the graphics represent for the selected data structure.

If you cannot see all of the nodes in the work area, either resize the screen or use the scroll bars on the bottom and/or right side to view the rest of the work area.

3.1.2. Choosing a Node Type:

Before entering any commands in "C++ Pointers" select a node type by clicking the radio button to the left of the desired node type (singly linked, doubly linked, or tree nodes). Then click one of the radio buttons labeled "int" and "string" to select a data type for the nodes. These radio buttons are located at the bottom right corner of the program window under the heading "Node Types." Once any commands have been entered and logged, the node type cannot be changed without restarting the program. If a lesson is open, it determines the node type, and the radio buttons are disabled. Otherwise the default node type is singly linked nodes that take integers as data.

3.2. Commands

To enter commands type C++ code in the text box underneath the heading "Command to Execute:" and press the "return" key to execute the command. This code must be syntactically correct (e.g. each line of code entered must end with a semicolon), and the command must be of the type supported by "C++ Pointers." The program will display error messages for syntax errors, runtime errors, invalid variables, and memory leaks.

Each command entered is added to the Prior Commands List.

3.2.1. Commands Supported by "C++ Pointers"

New Nodes: All nodes need to be referenced by a pointer; a node instantiated without a pointer would be inaccessible. Because of this, creating a new node requires a concurrent pointer assignment. The syntax is as follows:

p=new StringNode;
p=new IntNode;
p=new Node<Int>;
p=new Node<String>;

Note that p can have any pointer reference substituted for it, e.g. p->next->prev. On the screen, a link from the designated origin (p, in the case of the example) will point to the new node.

Deleting Nodes: Node deletion requires a reference to a node, for example:

delete p->right;

deletes the node referenced by the next field of the node that p points to.

Node deletion will leave dangling pointers, indicated visually by a grayed square where the pointer originated. Dangling pointers should be resolved before other commands are executed.

Data Field Assignments: The data to be assigned to a node must conform to the node type -- strings of three or less characters for string nodes, and integers of three or fewer digits for int nodes. The node to which data is to be assigned is referenced via pointer, as follows:


Pointer redirection and assignment: Pointers are updated and assigned in different ways, depending upon the type of data structure being built. C++ Pointers supports singly linked lists, doubly linked lists, and binary trees. Valid node-related pointer names are, for singly, doubly, and tree nodes respectively, next; next and prev; right and left.

To indicate a particular node, it is necessary to start with some initial pointer (i.e., p, q, r, or s) and some series of node-related pointers. For example:

 valid for singly and doubly linked nodes


valid for all node types


valid for doubly linked nodes


valid for doubly linked nodes


valid for tree nodes

A pointer reassignment requires a pair of the above, separated by an '=' to indicate the assignment.

s->next->prev = s->next->prev->next;

Below, a pointer to be removed is set to NULL:

p->left->left = NULL;

Memory leaks occur when a node becomes inaccessable, in other words, there are no pointers assigned to it. It is important to keep this in mind when redirecting pointers. "C++ Pointers" will bring up an error message when memory leaks occur, and you will have to select "Undo" from the "Commands" menu to continue.

If statements: If statements are supported, are the standard comparisons,
(i.e.., !, &&, ||, ==, !=, >, <, >= and <=). Syntax for an if statement is of the form:

if (boolean) action;
if (boolean) action else other action;

'Action' can be any other valid command (nesting if statements is not supported). The boolean argument is generally some sort of comparison, for example: p->next->data < q->next->prev->data.


3.2.2. The Command Menu

Undo: This option returns the data structure to its state prior to the execution of the command just executed and updates the log of commands. If a loop has just been executed, the entirety of the loop is undone. In other words, you cannot undo a part of a loop. Once you have undone a command, the "Undo" option is disabled until another undoable command has been executed.

Show Prior Commands: This option opens a window containing all logged commands (those commands entered in the command text entry box or loops and Undo). Undone commands appear in C++ style comments. When Check Lesson is selected a commented note appears in the Prior Commands window indicating that that the lesson has been checked. To print this list once the window is opened use the browser's "print" option. To save this list, cut or copy and paste the code into a program or text processor.

Clear All...: This option restarts the program. When you select this option, a dialog box appears to confirm the restart.

3.3. Loops

In "C++ Pointers" loops are not entered into the "Command to enter" text box on the main program window. Instead, select either the "For Loop..." or the "While Loop..." option under the "Loop" menu.

When one of these options has been selected, a window appears, and the command entry box in the main program window is disabled. The loop window has boxes for the loop condition and for each statement of the loop body (a maximum of six). Move the insertion point from one text entry box to the next by either clicking the desired box or pressing the "return" key to move to the next box. Type C++ code in these boxes just as you would with the text entry box in the main program window. This code must conform to C++ syntax (including semicolons and parentheses), and all code must be made up of commands accepted by "C++ Pointers."

To execute the loop click one of the two buttons at the bottom of the loop window. To run the loop to completion, once you have entered your commands for the loop, click the "Run" button. With this option the data structure will automatically change according to the commands in the loop. On the other hand, to step through the loop one line at a time click the "Step" button for each statement you wish to see evaluated. Each time you click the "Step" button the program will evaluate the statement that appears in the text entry box on the main program window. So that you can see the changes to the data structure, the main window will become the active window. To evaluate the next statement bring the loop window to the front and click the "Step" button again. The run button can be selected at any time to complete the execution of the loop.

When the loop has executed successfully, the loop window will close, the command entry box in the main program window will be enabled, and the display will reflect the changes made by the loop. However, if an error occurs during the execution of the loop, you can either close the loop window or select "Undo" in the "Commands" menu to undo all of the commands that have been evaluated as part of the loop. You can select "Undo" or close the loop window at any time while stepping through a loop. Selecting "Undo" at any point throughout the loop will undo the entire loop.

3.4. Lessons

There are ten default lessons for "C++ Pointers." Each lesson consists of an initial data structure and instructions that ask the student to alter the structure. These default lessons are stored at http://cs.beloit.edu/~pointers/lessons/. The instructor can create new lessons to use with the program and store these locally.

3.4.1. Running a Lesson

To run a lesson select the "Open Lesson..." option under the "Lesson" menu. This option will bring up a window that lists the default lessons according to the data structure type. To work on one of these lessons simply click the desired lesson. If you do not want to run one of the default lessons, enter the URL of another lesson in the text box on the right side of the screen and press the "return" key or click the "Get the Lesson" button. Keep in mind that when you start a lesson any work you've done prior to selecting "Open Lesson..." will be erased.

When the lesson opens "C++ Pointers" will display a data structure, and a new window will appear displaying the instructions. You can close this window if you wish to or put it in the background. Select "Show Lesson Instructions" in the "Lesson" menu, if you wish to see it again.

The instructions will ask you to change the data structure in a particular way. You can do this by either entering commands in the text entry box (see section 3.2), executing a loop (see section 3.3) or some combination thereof.

ÝTo check to see if you have modified the lesson correctly select "Check Lesson..." in the Lesson Menu. This option brings up a dialog box that will tell you if the lesson has been completed. (Note: "C++ Pointers" does not currently support this feature.)

To restart the lesson select "Start Lesson Over..." in the "Lesson" menu. A dialog box will appear to confirm a restart. Click the "Start Over" button to restart the lesson. This option returns the data structure to its state at the beginning of the lesson and clears the command log of all commands.

If you no longer wish to work on a lesson but would like to continue working with "C++ Pointers," select "Clear All..." in the "Commands" menu and click the "Clear All..." button in the dialog box.

You can start a new lesson at any time by selecting "Open Lesson" in the "Lesson" menu, but remember that if you open a new lesson, you will lose any work that you are currently working on.

3.4.2. Creating a Lesson

To make a new lesson first create the start state of the lesson by executing commands and/or running loops to set up an initial data structure for the lesson. Once you have the data structure the way you want it, select "Save as Lesson..." in the "Lesson" menu. A dialog box will appear asking if an initial state exists. If you are ready to save the current screen as the initial state, enter the instructions for your lesson in the text entry field of the dialog box and click "OK."

Clicking "OK" brings up an HTML window with the lesson encoding in it. You can now choose "Save As..." from the "File" Menu of your browser to save the lesson to your local hard drive. Save the file with the extension ".les". If you wish to make your lesson available to others, store the file in a public directory accessible over a network.

Search engine sitemap created by AutoSitemap.com