Variable Visualiser Documentation

Variable visualiser is an app designed to teach people who are new to C/C++ about variables and memory allocation. It allows the user to type in C++ code and see a visual representation of that code's affect on RAM.

RAM Panel

On the left is the RAM Panel which displays a simulation of a computer's RAM, divided into Heap, Static, and Stack sections.

Each of these section is in turn divided into bytes and each of these displays it's value and address in memory. Bytes are arranged in groups of four to represent the word size of a 32-bit machine.

The bytes are displayed in different colours to indicate their state, and when multiple bytes contribute to form one variable only their combined value is displayed.

Code Panel

To the right is the Code Panel where the user can type in C++ code or chose from one of several premade examples. To begin, try choosing from some of the premade examples and click Run to see the result, or repeatedly click Step to see the code processed one line at a time.

Watch Panel

The watch panel displays additional information about the byte or variable currently under the mouse:

Console Panel

The Console displays error messages if invalid C++ code is entered into the Code Window. I tried to make these errors helpful, but in some cases an inaccurate error, or even no error may be displayed. See the Verbose Logging option for other ways to check for errors.

Settings Panel

The Settings Panel contains options that can be toggled to change the way the app works.

• Initialise RAM to Zero (default On): If turned on unallocated RAM will be set to zero, emulating the behaviour of many IDEs operating in debug mode. When turned off, the RAM will begin with random garbage values which more accurately reflects the state of RAM likely to be encountered when a non-debug program runs.
• Use VS Debug Numbers (default On): Turns on the "magic numbers" used in Visual Studio to indicate the state of some uninitialized variables. The following magic numbers are supported:
• 0xCCCCCCCC: Memory has been allocated on the Stack but it has not been initialised.
• 0xCDCDCDCD: Memory has been allocated on the Heap but it has not been initialised.
• 0xDDDDDDDD: Memory on the Heap has been deleted.
• Contiguous Allocations (default On): When this option is enabled, all allocations will be contiguous in memory and padded to keep them aligned the way they would be within a struct or class. When disabled the variables will be allocated from an unpredictable area of RAM which is how individual Stack and Heap allocations usually work.
• Show Arrows (default On): Enables the arrows that are displayed connecting pointers to their pointees which can be helpful for visualising their relationship.
• Verbose Logging (default Off): When enabled, the app will print extra debugging information to the browser's developer console. This can sometimes be helpful when trying to work out why your C++ code isn't working if the Console hasn't provided enough information. Then again it may not be helpful at all.

Variable Visualiser supports basic C++ syntax for declaration, initialisation and assignment of variables. Control statements, functions, structs, and classes are not supported.

Supported Keywords

Only the following keywords are supported:

• Types: int, short, float, bool, char.
• Other: true, false, static, new, delete, nullptr.

Commenting

Single line comments are supported and can be placed on their own line or at the end of a code line. Block comments are not supported.

Variable Declaration

The following syntax is supported:

• int value; //Declaration without initialisation.
• int value = 5; //Declaration with initialisation.
• value = 5; //initialisation or assignment on a separate line.

Floating point numbers require a trailing 'f', boolean variables can only be initialised with true or false. Char types require single quotation marks.

• float value = 3.5f;
• bool value = true;
• char value = 'A';

Pointers

Pointers are supported and can be allocated and destroyed using the C++ keywords 'new' and 'delete'. malloc(), free(), and related C functions are not supported.

Both the address-of (&) and dereference (*) operators are supported, and theoretically any level of indirection is supported.

Static Variables

Variables can appear in the static region of RAM for two reasons: they are part of the static string table, or the static keyword was explicitly used.

• char* text = "hello world"; //The data for this string will be allocated from the static region.
• static int value = 5; //Any variable with the static keyword will be allocated from the static region.

Alignment and Padding

With "Contiguous Allocations" turned on in the Settings, the app emulates the way memory is aligned and padded in structs: Padding is inserted between variables to keep them aligned to byte boundaries divisible by the variable's size.

Arrays

Only one dimensional arrays are supported, but they can be allocated on both the stack and heap. Pointers and arrays can be used interchangeably and this comes with all the usual dangerous pitfalls, such as indexing beyond the end of a pointer's allocation.