Generally, communication with serial ports involves these steps (in no particular order):

• Searching for serial ports
• Connecting to the serial port
• Starting the input output streams
• Adding an event listener to listen for incoming data
• Disconnecting from the serial port
• Sending Data
• Receiving Data

I wrote an example program that includes all of those steps in it and are each in their own separate method within the class, but first I will go through my hardware set up.

Hardware Setup

My current hardware setup is as follows:

• PC connected to an XBee
• Arduino connected to an XBee

User input is given from the PC through the a Java GUI that contains code for serial communication, which is the code presented here.

The Arduino is responsible for reading this data.  This set up is pretty much using my computer as a remote control for whatever device is on the Arduino end.  It could be a motor control, on-off switch, etc.

Existing Code

The purpose of this post is to discuss serial programming in Java, and not GUI’s.  However, I did create a GUI for testing purposes.  See the Code Downloads section for the actual files.

Above is the picture of the GUI complete with the buttons that I use to interact with the program.  I also added key bindings which I can use to control the throttle.

When the program is first started, none of the GUI elements will work except for the combo box and the connect button.  Once a successful connection is made the controls are enabled.  This is done through the use of the setConnected(true) and the toggleControls() methods shown in the example code that follows.

Imports

The imports i used for this program were as follows:

import gnu.io.*;
import java.awt.Color;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.Enumeration;
import java.util.HashMap;
import java.util.TooManyListenersException;

Depending on the Java IDE it might already know to tell you to use these imports except for the first one.  That first import is specific to RXTX, and all its library methods/classes are in there.

Class Declaration

The code here reads:

public class Communicator implements SerialPortEventListener

I named my class Communicator, but the name is really up to the programmer.  The name pretty much reflects its intended use.

The class should also implement the SerialPortEventListener class.  This is a class in RXTX and is required in order to receive incoming data.

On some IDE’s this may generate a public void method called serialEvent().  This method will be defined later.

Class Variables and Constants

Below are the variables and constants that I defined in my class.  What the variables are for is in the comments but a more detailed explanation will follow.

    //passed from main GUI
    GUI window = null;

    //for containing the ports that will be found
    private Enumeration ports = null;
    //map the port names to CommPortIdentifiers
    private HashMap portMap = new HashMap();

    //this is the object that contains the opened port
    private CommPortIdentifier selectedPortIdentifier = null;

I could have easily put the variable definitions in the constructor but it wouldn’t change anything.

The GUI object is another class that I wrote separate from this one that contains all the GUI elements.  The GUI class extends javax.swing.JFrame.

The HashMap is for mapping each of the ports’ names to the actual object. What that means is that I can associate (put() method) the name of a serial port, say a string that says COM1, to an object in the code.  Later, I can access the name COM1 from the HashMap by using the get() method and it will return the object that it was associated with previously.

The CommPortIdentifiers object is needed to gather the list of ports that are available for connection. by using its getPortIdentifiers() method.

The SerialPort object is for storing the data for the port once a successful connection is made.

The InputStream and OutputStream is the object that is required for sending and receiving data.

The Boolean variable bConnected is just a flag that I use for enabling and disabling elements on the GUI.

The constant TIMEOUT is a number required when opening the port so that it knows how long to try for before stopping.

The constants for the ASCII values are some values that I use to send through the output stream that act as delimiters for data.

The string logText is basically what the comment says.  When stuff happens in the program, the program stores a string in this variable and it will be appended to a text area in the GUI.

Searching for Available Serial Ports

The method below is for searching for available serial ports on the computer.  Code adapted from Discovering Available Comm Ports from the Reference Material.

    //search for all the serial ports
    //pre style="font-size: 11px;": none
    //post: adds all the found ports to a combo box on the GUI
    void searchForPorts()
    {
        ports = CommPortIdentifier.getPortIdentifiers();

        <span style="color: blue;">while (ports.hasMoreElements())
        {
            CommPortIdentifier curPort = (CommPortIdentifier)ports.nextElement();

            //get only serial ports
            <span style="color: blue;">if (curPort.getPortType() == CommPortIdentifier.PORT_SERIAL)
            {
                window.cboxPorts.addItem(curPort.getName());
                portMap.put(curPort.getName(), curPort);
            }
        }
    }

The method getPortIdentifiers() returns an Enumeration of all the comm ports on the computer.  The code can iterate through each element inside the Enumeration and determine whether or not it is a serial port.  The method getPortType() can identify what kind of port it is.  If it is a serial port, then the code will add its name to a combo box in the GUI (so that users can pick what port to connect to).  The serial port that is found should also be mapped to the HashMap so we can identify the object later.  This is helpful because the names listed in the combo box are the actual names of the object (COM1, COM2, etc), and so we can use these names to identify the actual object they are tied to.

Connecting to the Serial Port

The method below is for connecting to the serial port once they have been found (see previous section).  See How to Open A Serial Port in the Reference Material for more information.

    //connect to the selected port in the combo box
    //ports are already found by using the searchForPorts
    //method
    //post: the connected comm port is stored in commPort, otherwise,
    //an exception is generated
    public void connect()
    {
        String selectedPort = (String)window.cboxPorts.getSelectedItem();
        selectedPortIdentifier = (CommPortIdentifier)portMap.get(selectedPort);

        CommPort commPort = null;

        try
        {
            //the method below returns an object of type CommPort
            commPort = selectedPortIdentifier.open("TigerControlPanel", TIMEOUT);
            //the CommPort object can be casted to a SerialPort object
            serialPort = (SerialPort)commPort;

            //for controlling GUI elements
            setConnected(true);

            //logging
            logText = selectedPort + " opened successfully.";
            window.txtLog.setForeground(Color.black);
            window.txtLog.append(logText + "n");

            //CODE ON SETTING BAUD RATE ETC OMITTED
            //XBEE PAIR ASSUMED TO HAVE SAME SETTINGS ALREADY

            //enables the controls on the GUI if a successful connection is made
            window.keybindingController.toggleControls();
        }
        catch (PortInUseException e)
        {
            logText = selectedPort + " is in use. (" + e.toString() + ")";

            window.txtLog.setForeground(Color.RED);
            window.txtLog.append(logText + "n");
        }
        catch (Exception e)
        {
            logText = "Failed to open " + selectedPort + "(" + e.toString() + ")";
            window.txtLog.append(logText + "n");
            window.txtLog.setForeground(Color.RED);
        }
    }

Using the HashMap we can retrieve the CommPortIdentifier object from the string that was mapped earlier.  This is achieved through the HashMap’s get() method.  The object must also be casted as a CommPortIdentifier because the get() method has a return type of Object.

The setConnected method just changes a boolean flag so that the program can store whether or not it is connected to a serial port or not.

The CommPort must also be initialized because the port object will be stored here once a successful connection is made.

The main method of interest here is the open() method.  This instructs the program to open the port, and this method will return the object for the opened port, which I store in in the previously initialized CommPort object.  I then cast this object as a SerialPort and store it as well.  This is helpful for accessing the methods and variables specific to the SerialPort class.

It should also be noted that the open() method requires the use of a try-catch block.  So applying that, I catch two different exceptions.  The PortInUseException is what the name says.  If the port is in use, then this exception is thrown.  The next catch block is just for the generic exceptions that occur.  I never came across that during testing, nor do I know how to replicate that.

I neglected to include any code for setting the baud rate and other settings on the XBee’s (see Hardware Configuration), because I already set those parameters previously using X-CTU (more on setting up XBee’s here).

Initializing the Input and Output Streams

This method is pretty short and is pretty straightforward to read.

    //open the input and output streams
    //pre style="font-size: 11px;": an open port
    //post: initialized input and output streams for use to communicate data
    public boolean initIOStream()
    {
        //return value for whether opening the streams is successful or not
        boolean successful = false;

        try {
            //
            input = serialPort.getInputStream();
            output = serialPort.getOutputStream();
            writeData(0, 0);

            successful = true;
            return successful;
        }
        catch (IOException e) {
            logText = "I/O Streams failed to open. (" + e.toString() + ")";
            window.txtLog.setForeground(Color.red);
            window.txtLog.append(logText + "n");
            return successful;
        }
    }

The streams are initialized by returning the input and output streams of the open serial port.  In order for the serial port object to not be null, it must store the object for the open serial port.

The getInputStream() and getOutputStream() methods both require a try-catch block.  The important exception to catch here is the IOException to signify whether the streams failed to open or not.  For more information see How to Open A Serial Port in the Reference Material.

I also call a method called writeData(0, 0).  This is the method that encapsulates the code required to write serial data.  More on that later.  Right now it is just used to set variables on the microcontroller side to zero.

Setting Up Event Listeners to Read Data

Once the port is open, the serial port must know whenever there is data to be read.  This approach is event driven rather than by polling.  When the event is hit, a special block of code will run.  This is advantageous to polling because polling requires constantly asking if data is available.  The code for the event driven approach is below.  See Event Based Two Way Communication for more information.

    //starts the event listener that knows whenever data is available to be read
    //pre style="font-size: 11px;": an open serial port
    //post: an event listener for the serial port that knows when data is received
    public void initListener()
    {
        try
        {
            serialPort.addEventListener(this);
            serialPort.notifyOnDataAvailable(true);
        }
        catch (TooManyListenersException e)
        {
            logText = "Too many listeners. (" + e.toString() + ")";
            window.txtLog.setForeground(Color.red);
            window.txtLog.append(logText + "n");
        }
    }

The code here is pretty much the whole reason why this class implements SerialPortEventListener.  The parameter for adding the event listener is just the object itself.  The base class has a method called serialEvent(event) that should be overridden before the event code will work.  Overriding that method defines what happens when the event is hit.

The method addEventListener(this) is the event that is always checking for SerialEvents.  It isn’t really important to know what the events actually are, just that the one we’re interested in is the one that tells us whenever data is received.  Adding the event listener is complemented by the method notifyOnDataAvailable(true), which definitely helps us achieve what I mentioned previously.

This code requires a try-catch box.  The exception here is that there may be too many event listeners.  I only use one in the code, so this exception should never be hit.

Disconnecting from the Serial Port

Once all the communication is completed, the serial port must be disconnected.  In some instances, some ports stay stuck open, which isn’t exactly a good thing.

    //disconnect the serial port
    //pre style="font-size: 11px;": an open serial port
    //post: closed serial port
    public void disconnect()
    {
        //close the serial port
        try
        {
            writeData(0, 0);

            serialPort.removeEventListener();
            serialPort.close();
            input.close();
            output.close();
            setConnected(false);
            window.keybindingController.toggleControls();

            logText = "Disconnected.";
            window.txtLog.setForeground(Color.red);
            window.txtLog.append(logText + "n");
        }
        catch (Exception e)
        {
            logText = "Failed to close " + serialPort.getName()
                              + "(" + e.toString() + ")";
            window.txtLog.setForeground(Color.red);
            window.txtLog.append(logText + "n");
        }
    }

The code here requires a try-catch block so there it is.  The exception to catch here is pretty generic.

Before closing the port, I reset the data on the microcontroller.  That step is optional depending on the application.  For example, if the value sent to the microcontroller is controlling the speed of a motor, I’d want the motor to turn off if I turn off the remote control.

The event listener should be removed as it is no longer needed.

The method to close the port is the close() method.

The input and output streams should also be closed via the same method as above.

See How to Close A Serial Port in the Reference section for more information.

Reading Data – The serialEvent Method

This is a follow-up to the section on preparing to Read Data.  It has information on how to process the data that the program reads.

    //what happens when data is received
    //pre style="font-size: 11px;": serial event is triggered
    //post: processing on the data it reads
    public void serialEvent(SerialPortEvent evt) {
        if (evt.getEventType() == SerialPortEvent.DATA_AVAILABLE)
        {
            try
            {
                byte singleData = (byte)input.read();

                if (singleData != NEW_LINE_ASCII)
                {
                    logText = new String(new byte[] {singleData});
                    window.txtLog.append(logText);
                }
                else
                {
                    window.txtLog.append("n");
                }
            }
            catch (Exception e)
            {
                logText = "Failed to read data. (" + e.toString() + ")";
                window.txtLog.setForeground(Color.red);
                window.txtLog.append(logText + "n");
            }
        }
    }

Since we only want to read data if it exists, we test the condition in the if statement above.  This could be redundant because we wouldn’t be in this method if the event never got triggered.

Reading the data requires a try-catch block.  The read() method returns an integer, but the value in it is actually a byte value so this is casted to a byte, in which I store in a variable called singleData.  When I was testing this code before, I noticed that the data being read would always have random new line characters in it, and I never knew why this happened.  I never wrote any new line characters.  Since I don’t want these, I add an if condition saying that if it encounters that, don’t display that data on the screen.

Java also has a nice way of converting bytes to a string.  A byte array can be used as a parameter when initializing a string, which is what I’ve done when I assign a value to logText.

The exception here is just the usual generic one.

Writing Data

Here is the method for writing data.  In my application, I am writing two integers sequentially to my microcontroller.  Data that is sent to the MCU can be used for such things such as controlling motor speeds, which is what I am trying to do here.  I hope to use the data sent do control the PWM duty cycle of the motor for speed control.

    //method that can be called to send data
    //pre style="font-size: 11px;": open serial port
    //post: data sent to the other device
    public void writeData(int leftThrottle, int rightThrottle)
    {
        try
        {
            output.write(leftThrottle);
            output.flush();
            //this is a delimiter for the data
            output.write(DASH_ASCII);
            output.flush();

            output.write(rightThrottle);
            output.flush();
            //will be read as a byte so it is a space key
            output.write(SPACE_ASCII);
            output.flush();
        }
        catch (Exception e)
        {
            logText = "Failed to write data. (" + e.toString() + ")";
            window.txtLog.setForeground(Color.red);
            window.txtLog.append(logText + "n");
        }
    }

The write() method here requires a try-catch block just like many of the other methods used for serial communication.  Using the output stream, I call that method to write an integer value.  I also write a dash and a space to separate the actual data being read.  See the ASCII Table for the values of what these characters should be.  This helps me differentiate the sets of data that is sent back and forth.  The dash separates the two integers being sent and the space separates the entire set.  On the Arduino end, four called to read() can separate the data without mixing things up.  Example of that later.

Putting All the Java Code Together

Once all these methods are setup, they need to be called somewhere in the program so we can put them to use.  When the program starts, the code for searching for serial ports will run so that it can populate the combo box on the GUI.  The GUI buttons also need to be disabled to reflect the fact they should be disabled when there is no connection to a port.  When the connect button is pressed, the input and output streams are started and the event listener is added.  The code for that is shown below.

        private void btnConnectActionPerformed(java.awt.event.ActionEvent evt) {
            communicator.connect();
            if (communicator.getConnected() == true)
            {
                if (communicator.initIOStream() == true)
                {
                    communicator.initListener();
                }
            }
        }

The if statement is needed such that the code will not run if a successful connection was not made.  This is the precondition for the initIOStream() and the initLIstener() methods.

When the user decides to disconnect from the serial port, the user only needs to call the disconnect() method when the disconnect button is pressed.

The up/down arrows on my GUI are set to write data to the serial port when they are pressed.  When data is written to the Arduino, the MCU will send the data back to the Java program, which will signal the event listener to display that data back to the screen.

Arduino Code

The Arduino code is pretty straight forward.  There are just a few calls to the read() method.

Update 6 May 2012: the syntax for the Arduino code has updated since the writing of this article.  Apparently, the lines

Serial.print(separator, BYTE);
Serial.print(space, BYTE);

are no longer valid and have since been replaced by the following:

Serial.write(byte(separator));
Serial.write(byte(space));

The code below hasn’t been edited with this change, but basically the code required for writing a byte value through serial communication has changed.

// this is where we will put our data
int left = 0;
int right = 0;
byte space = 0;
byte separator = 0;

void setup(){
  // Start up our serial port, we configured our XBEE devices for 38400 bps. 
  Serial.begin(9200);
}

void loop(){
  // handle serial data, if any
  if (Serial.available() >= 4){
    left = Serial.read();
    separator = Serial.read();
    right = Serial.read();
    space = Serial.read();
    Serial.flush();

    Serial.print(left);
    Serial.print(separator, BYTE);
    Serial.print(right);
    Serial.print(space, BYTE);
    Serial.print("n");
  }
}

I first declare four variables to reflect the fact that I’m writing four different variables to the serial port.

In the loop method, I added a condition which will check whether there are four pieces of data available before reading them.  This again reflects the fact I’m writing four values.

The four variables initially declared store the values in the order that they are written, and then are just printed to the screen.

The print() method is able to convert the byte value to an actual character by adding a second parameter called BYTE.  The left and right variables don’t need it because the values written were integers to begin with, however, the dash and space characters were written as ASCII values.

For more information about Arduino and Java, and Arduino’s Serial library, please refer to those in the Reference Section.

Code Downloads

Here are the code downloads for the GUI, key bindings and the serial communication.  WordPress doesn’t allow uploads of zip or java files so I uploaded it all to Megaupload.

Link to download: http://www.mediafire.com/?z2l26ncypmzn20z

Other Examples

There are also other sites I looked at which had example code for serial port communication in Java.  The sites are Programming Serial and Parallel Ports and Serial Port Access Using RXTX in Java, which are both in the Reference section.

Reference Material

Below are a bunch of links to reference sites that I used to find some of the information written here.  I mostly referred to bits and pieces of each article to understand the serial code and to come up with the example I present here.  The list is in the order that I referenced them.

Discovering Available Comm Ports

http://rxtx.qbang.org/wiki/index.php/Discovering_available_comm_ports

The code on this page is pretty specific to the title of this heading, and the code is pretty easy to follow.

How to Open A Serial Port

http://embeddedfreak.wordpress.com/2008/08/08/how-to-open-serial-port-using-rxtx/

This page provides a very concise and detailed explanation on what each line of code does in order to get a serial port open.  Definitely work a look if you’re trying to understand the code.

Event Based Two Way Communication

http://rxtx.qbang.org/wiki/index.php/Event_Based_Two_Way_Communication

This page has example code on how to connect to a serial port and how to interact with it.  The code here uses events, rather than polling, to send data back and forth, which means that whenever data is received, the event code is triggered.

How to Close A Serial Port

http://embeddedfreak.wordpress.com/2008/08/08/how-to-close-serial-port-in-rxtx/

This article is written by the same author who wrote the article on how to open serial ports.  Good example code here.

ASCII Table

http://www.asciitable.com/

Having the ASCII Table is quite handy for serial data because data being sent and written are bytes, so being able to know what byte values correspond to what character really helps.

Arduino and Java

http://www.arduino.cc/playground/Interfacing/Java

This article discusses how to use the serial port communication with Java and Arduino, which is exactly what I am after.  It has example code on pretty much the entire process of serial port communication, but it may be too much to read since there is little explanation about the code.

Arduino Serial Class

http://arduino.cc/en/Reference/Serial

A good reference for Arduino’s Serial class methods.  Also has example code to look at.

Programming Serial and Parallel Ports

This article provides a brief introduction to programming serial ports and has information on the steps required to talk to the serial port.  However, the code examples in there may be hard to follow for someone new to serial programming.

Serial Port Access Using RXTX in Java

http://gomultidomain.blogspot.com/2008/06/serial-port-access-using-rxtx-in-java.html

This page also has complete code for serial communication in Java, but what I was looking for here was how to use the write method to send serial data from Java.

“This is a technical document describing the UnrealScript language. It’s not a tutorial, nor does it provide detailed examples of useful UnrealScript code. For examples of UnrealScript the reader is referred to the source code of the engine, which provides tens of thousands of lines of working UnrealScript code which solves many problems such as AI, movement, inventory, and triggers. A good way to get started is by looking at the “Actor”, “Object”, “Controller”, “Pawn”, and “Weapon” scripts.”

http://udn.epicgames.com/Three/UnrealScriptReference.html

asm (seldom used)

• Used to insert assembly language commands directly into the code. This function is very tricky to use even for professional programmers and can cause portability issues.
  

  asm(“instruction”);

auto

• Used to declare local variables but is purely optional.
  

  auto int i = 5;

  The previous declaration thus has identical meaning to the following declaration.

  int i = 5;

bool (C++ only)

• Used to declare a Boolean logic variable; a variable that can have the value true or false. This variable type is normally 8 bits (1 byte) long.
  

  bool t = true;

break

• Used to break out of a loop independant of the loop condition. Also, used to finish a switch statement, keeping the program from “falling through” to the next case in the code.
  

  while(x < 100)
  {
      if(x < 0)
           break;
      cout << x << endl;
      x++;
  }
  

case

• Used as a label to declare a single test in a switch statement.
  

  case 1: command1;
          command2;
          break;
  

catch (C++ only)

• Used to handle exceptions generated by a throw statement.
  

  catch(const char* e)
  {
      //handle exception
  }
  

char

• Used to declare character variables. This variable type is normally 8 bits (1 byte) long.
  

  char c = ‘h’;

class (C++ only)

• Used to define a new class. Members of the class are private by default unless listed under the protected or public labels.
  

  class class-name : inheritance-list
  {
      public:
          public-members-list;
      protected:
          protected-members-list;
      private:
          private-members-list;
  } object-list;
  

  • class-name is the name of the class that is being created.
  • inheritance-list is the optional list of classes inherited by the new class.
  • public-members-list is the list of public members of the class.
  • protected-members-list is the list of protected members of the class.
  • private-members-list is the list of private members of the class.
  • object-list is an optional list used to immediately instantiate 1 or more instances of the class.

  class Date
  {
  public:
      void display();
  
  private:
      int day;
      int month;
      int year;
  }
  

const (C++ only)

• Used to tell the compiler that a certain object should not be modified once it has been initialized.
  

  const int i = 5;

• Used to declare a pointer so that the value of the pointer (the memory location to which it points) can be modified, but the data in the memory location cannot be changed.
  

  const int* j = new int(3);

• Used to declare a pointer so the that value of the pointer (the memory location to which it points) cannot be modified, but the data in that memory location can be changed.
  

  int* const j = new int(3);

• Used to declare a member function that does not modify the object’s state, meaning that it should be used for methods like print so that data in the object cannot be changed accidentally. If and attempt is made to modify the object in any way, a compilation error will be triggered.
  

  void print(bool verbose) const;

const_cast (C++ only, seldom used)

• Used to remove the const protection on a variable as long as the original variable was not declared as a const. The target type must be the same as the original type.
  

  const_cast<target_type> (object);

continue

• Used to jump to the next iteration of a loop. The following example will print out all of the numbers from 1 to 20 except for 10.
  

  for(int i = 0; i < 21; i++)
  {
      if(i == 10)
          continue;
      cout << i << endl;
  }
  

default

• Used as a label to declare the default case of a switch statement.
  

  case 1:  command1;
           command2;
           break;
  
  default: command1;
           command2;
           break;
  

delete (C++ only)

• Used to free memory allocated for a pointer back to the heap. The argument should have been allocated through a call to new. To delete an array, use the following form of delete: delete[]
  

  delete p;
  delete[] pArray;

do

• Used to create a loop that is executed at least once. The terminating condition is tested at the end of the loop.
  

  do
  {
      cout << "hello worldn";
      i++;
  } while(i < 5)
  

double

• Used to declare a double-precision floating-point type variable. This variable type is normally 64 bits (8 bytes) long.
  

  double d = 12.55;

dynamic_cast (C++ only, seldom used)

• Used to cast from one type to another with a check performed at runtime. If the cast types are incompatible, NULL is returned.
  

  dynamic_cast<target_type> (object);

else

• Used for an alternative condition in an if statement.
  

  if(i == 1)
  {
      // do something
  }
  else
  {
      // do something else
  }
  

enum

• Used to define an enumerated type. Each of the names in the name-list are given a distinct value. This should be used in place of defining variables using “magic numbers” (eg. int Monday = 0, int Tuesday = 1, etc).
  

  enum name {name-list};

  • name is the name of the enumerated type that was created
  • name-list is the list of names of the elements

  enum weekdays {Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday};

explicit (C++ only)

• Used to make sure that a constructoor is only used for the creation of new values and not used for the implicit conversion between two different types. It will only be be used if the initialization exactly matches the call to that constructor. This keyword is only needed with one-argument constructors.
  

  class vector
  {
      ...
      explicit vector(int v);
      ...
  }
  

  Using this keyword, some mysterious errors can be caught by the compiler like the following:

  vector<int> v(10);
  v = 5; // error, meant to write v[0] = 5
  

  The problem in this code if the explicit keyword was not specified is that the v = 5 statement would invoke the constructor, creating a new vector of size 5 and destroying the old one.

export (C++ only, seldom used)

• Used to export a template to other modules. Most compilers require template definitions to be explicitly specified in the header file since the Comeau C++ compiler seems to be the only compiler that supports this keyword.
  

  // In MyTemplateFunction.h
  template
  void myTemplateFunction(const T &t1);
  
  // In MyTemplateFunction.cpp
  export template
  void myTemplateFunction(const T &t1)
  {
      ...
  }
  

extern

• Used to inform the compiler of variables and functions that are defined outside of the current scope or module. Variables defined as extern will not have space allocated for them since they are defined elsewhere.
  

  extern char* message;

false (C++ only)

• Used to represent the Boolean value false.
  

  bool b = false;

float

• Used to declare a single-precision floating-point type variable. This variable<br> type is normally 32 bits (4 bytes) long.
  

  float f = 3.5;

for

• Used to create a loop that is meant to initialize, test and update a variable.
  

  for(int i = 0; i < 10; i++)
  {
      cout << "i is " << i << endl;
  }
  

friend (C++ only)

• Used to allow another class or function to have access to the private features of that class.
  

  friend void print(bool verbose);
  friend class Vector;

goto (seldom used)

• Used to jump to another location in a function specified by a label. This is generally considered harmful and should not be used unless necessary.
  

  goto labelA;
  ...
  labelA:

if

• Used to create a conditional branch statement so that different code can be executed under different conditions. The conditions are evaluated in the order that they appear in the code.
  

  if (i < 0)
  {
      cout << "i is negative";
  }
  else if(i == 0)
  {
      cout << "i is 0n";
  }
  else
  {
      cout << "i is posativen";
  }
  

inline (C++ only)

• Used to tell the compiler that the function an its body are inserted into the calling code meaning that it has to expand the function in-place instead of just insert a call to the function. Functions that have static data, loops, switches or recursive calls cannot be inlined.
  

  inline int test(int A)
  {
      ...
  }
  

int

• Used to declare an integer type variable. This variable type is normally 32 bits (4 bytes) long.
  

  int i = 3;

long

• Used as a data type modifier for the int and double types to indicate that they may have more bytes then the type has available. This variable type is normally 32 or 64 bits (4 or 8 bytes) long.
  

  long int i = 100000;

mutable (C++ only)

• Used to specify that it is a data field that can be modified even if another part of the data is declared const.

namespace (C++ only)

• Used to create a new scope. Once created, the namespace must be refered to either directly or with the using keyword.
  

     namespace CartoonNameSpace
      {
          int HomersAge;
  
          void incrementHomersAge()
          {
              HomersAge++;
          }
      }
      int main() {
          ...
          CartoonNameSpace::HomersAge = 39;
          CartoonNameSpace::incrementHomersAge();
          cout << CartoonNameSpace::HomersAge << endl;
          ...
      }
  

new (C++ only)

• Used to allocate a new block of memory for the given type from the heap, and return a pointer to that block of memory. Allocating arrays can be done by providing the size of the array in square brackets.
  

  pointer = new type;
  pointer = new type( initializer );
  pointer = new type[size];

  • pointer is a pointer to the type that you want to allocate the memory for
  • type is the type of the item that is to be stored in the memory that is allocated
  • initializer is the optional information for the constructor
  • size is the size of the array to create

operator (C++ only)

• Used to specify that you are overloading an operator.
  

     return-type class-name::operator#(parameter-list)
      {
          ...
      }
  

  • return-type is the return type for the function
  • class-name is the name of the class that the operator is a part of. If it is not part of a class, this can be left out along with the ‘::‘.
  • # is the operator that is to be overloaded, such as ‘++’. You cannot overload the #, ##, ., :, .*, or ? tokens.
  • parameter-list is the list of parameters that the operator will take. For unary operators, parameter-list should be empty, and for binary operators, parameter-list should contain the operand on the right side of the operator (the operand on the left side is passed as this).
• There are special conventions for some operators, such as the unary ++ and — operators.
  • The unary ++ operator has both prefix (++object and postfix (object++) versions.

  •    return-type class-name::operator++()
        {
            ...
        }
    

    overloads the prefix version (the value returned is the value of the object after it is incremented, so this is also known as the pre-increment version because the increment takes place before the value is returned). There is no parameter specified because ++ is a unary operator.

  •    return-type class-name::operator++( int )
        {
            ...
        }
    

    overloads the postfix version (the value returned is the value of the object before it is incremented, so this is also known as the post-increment version because the increment takes place after the value is returned). The parameter int is not really a parameter (++ is still a unary operator) but is there soley to differentiate the prefix and postfix versions.

private (C++ only)

• Used within a class declaration to specify features of that class that can only be accessed by itself and its friends.
  

  class Date
  {
  public:
      void display();
  
  private:
      int day;
      int month;
      int year;
  }

• Used to inherit a base class privately, which causes all public and protected members of the base class to become private members of the derived class.
  

  class AlarmClock : private Clock
  {
  public:
      void display();
  
  }

protected (C++ only)

• Used within a class declaration to specify features of that class that are private to its own class, but can be inherited by a derived class.
  

  class Date
  {
  public:
      void display();
  protected:
      int day;
      int month;
      int year;
  }

• Used to inherit a base class, which causes all public and protected members of the base class to become protected members of the derived class.
  

  class AlarmClock : protected Clock
  {
  public:
      void display()
  }

public (C++ only)

• Used within a class declaration to specify features of that class that are accessable to everyone.
  

  class Date
  {
  public:
      void display();
  protected:
      int day;
      int month;
      int year;
  }

• Used to inherit a base class publically, which causes all public and protected members of the base class to become public and protected members of the derived class.
  

  class AlarmClock : public Clock
  {
  public:
      void display()
  }

register

• Used to reccommend that a varibale be placed into a processor register so that it is optimized for speed but the compiler is not obliged to do so. This keyword is rarely used anymore since compilers have become better than programmers at optimizing code.

reinterpret_cast (C++ only), seldom used

• Used to change one data type in a non-portable way. It is normally used to cast between incompatible pointer types.
  

  reinterpret_cast<target_type> (object);

return

• Used to cause the execution to jump from the current function back to the one that called it. An optional value can be returned but the function must specify the type that it will return.
  

  return;
  return 5;

short

• Used as a data type modifier for the int type to indicate that there may be less bytes then the type has available. This variable type is normally 16or 32bits (2 or 4bytes) long.
  

  short int i = 5;

signed

• Used to specify that the number type provided could potentially be negative, so it must be stored in a different format. This is the default representation that is chosen by most compilers if either signed or unsigned is not specified.
  

  signed int i = -12;

sizeof

• Used to return the size of the object (in bytes) that is passed to it.
  

  int i = 5;
  int size = sizeof( i );

static

• Used outside any function or class as a qualifier to a variable declaration makes the scope of the variable the file in which the variable is declared, and the extent is permanent (i.e., it is in the static segment).
  

  static int i;

• Used inside a function as a qualifier to a variable declaration makes the scope of the variable the function in which the variable is declared, and the extent is permanent (i.e., it is in the static segment).
  

  void foo()
  {
      static int i;
  }

• Used inside a class as a qualifier to a variable declaration makes the scope of the variable the class in which the variable is declared, and the extent is permanent (i.e., it is in the static segment).
  

  class bar
  {
      static int i;
  }

• Used outside any class as a qualifier to a function declaration makes the scope of the function the file in which the function is declared. As with all functions, the instructions for the function are in the code segment.
  

  static void foo()
  {
  }

• Used inside a class as a qualifier to a function (method) declaration makes the scope of the function the class in which the function is declared (as with all methods), and the instructions for the method are in the code segment (as for all functions). What is different is that a static method is invoked without requiring an object, using the qualifier syntax class::staticMethod( parameters ), although it can also be invoked on an object in the class in the usual way. Because no object is associated with a static method, only static member variables and other static member functions can be invoked by a static method.
  

  class bar
  {
      static void foo();
  }

  Note: A method in a class cannot be both “static” and “virtual”. The reason for this is that virtual functions have to know the object to which they apply (because of polymorphism) but static methods are not applied to an object.

static_cast (C++ only, seldom used)

• Used for a normal conversion between types. No runtime checking is performed.
  

  static_cast<target_type> (object);

struct

• Used to create a structure like a class, but the members are public by default instead of private. In C, structs can only contain data, cannot have inheritance and cannot have data with different visibilities.
  

  struct struct-name : inheritance-list
  {
          public-members-list;
      protected:
          protected-members-list;
      private:
          private-members-list;
  } object-list;

  • struct-name is the name of the struct that is being created.
  • inheritance-list is the optional list of structs inherited by the new struct.
  • public-members-list is the list of public members of the struct.
  • protected-members-list is the list of protected members of the struct.
  • private-members-list is the list of private members of the struct.
  • object-list is an optional list used to immediately instantiate 1 or more instances of the struct.

  struct Date
  {
      int day;
      int month;
      int year;
  }

switch

• Used to test an expression of an integer value against many constant integer values and is commonly used to replace large if()…else if()… statements. Break statements are required between each case statement, otherwise execution will “fall-through” to the next case statement. The default case is optional. If provided, it will match any case not explicitly covered by the preceding cases in the switch statement.
  

  char keystroke = getch();
  switch( keystroke )
  {
      case 'a':
      case 'b':
      case 'c':
      case 'd':
          KeyABCDPressed();
          break;
      case 'e':
          KeyEPressed();
          break;
      default:
          UnknownKeyPressed();
          break;
  }
  

template (C++ only)

• Used to create generic functions and can operate on data without knowing the nature of that data. They accomplish this by using a placeholder data-type for which many other data types can be substituted.
  

  template void genericSwap( X &a, X &b )
  {
      X tmp;
  
      tmp = a;
      a = b;
      b = tmp;
  }
  

this (C++ only)

• Used as a pointer to the current object. All member functions of a class have this pointer.
  

  this.print();

throw (C++ only)

• Used together with try and catch statements to create an exception handling system. Throw is used to generate an exception.
  

  try
  {
      cout << "Before throwing exception"<< endl;
      throw 42;
      cout << "Shouldn't ever see this"<< endl;
  }
  catch( int error )
  {
      cout << "Error: caught exception " << error << endl;
  }
  

true (C++ only)

• Used to represent the Boolean value true.
  

  bool b = true;

try (C++ only)

• Used to attempt to execute exception-generating code.
  

  try
  {
      cout << "Before throwing exception" << endl;
      throw 42;
      cout << "Shouldn't ever see this" << endl;
  }
  catch( int error )
  {
      cout << "Error: caught exception " << error << endl;
  }

typedef

• Used to create a new type from an existing type.
  

  typedef int seconds;

typeid (C++ only, seldom used)

• Used to get a reference to a type_info object that describes the object it was passed.
  

  typeid(object);

typename (C++ only)

• Used to describe an undefined type or in place of the class keyword in a template declaration.

union

Used to create multiple data fields that will occupy the same memory location.

union Data
{
    int i;
    char c;
};

unsigned

• Used to specify that the int or char provided can only be posative and can therefore contain a larger number since there is no need to worry about representation of negative numbers.
  

  signed int i = -12;

using (C++ only)

• Used to import a namespace into the current scope.
  

  using namespace std;

virtual (C++ only)

• Used to create virtual functions that can be overridden by derived functions.
  • A virtual function indicates that a function can be overridden in a subclass, and that the overridden function will actually be used.
  • When a base object pointer points to a derived object that contains a virual function, the decision about which version of that function to call is based on the type of object pointed to by the pointer, and this process happens at runtime.
  • A base object can point to different derived objects and have different versions of the virual function run.

  virtual void print();

• Used to create a pure virtual function which is a virtual function that must be overriden by some derived class.
  

  virtual void print() = 0;

• Note: A method in a class cannot be both “virtual” and “static”.

void

• Used to denote functions that return no value.
  

  void print()
  {
      cout << "printn";
  }
  

• Used to create generic variables which can point to any type of data.
  

  void *p = 5;
  

• Used to declare an empty parameter list.
  

  void print( void )
  {
      cout << "printn";
  }

volatile

• Used to inform the compiler that the variables value can change in unexpected ways (i.e. through an interrupt), which could conflict with optimizations that the compiler might perform, so therefore the compiler will not optimize these variables.
  

  volatile Date d;

wchar_t

• Used to declare a wide character variable. This variable type is normally 16 bits (2 bytes) long.
  

  wchar_t c = ‘c’;

while

• Used as a looping construct that will evaluate a list of statements as long as the condition is true. Note: if the condition starts off as false, the list of statements will never be executed. (You can use a do loop to guarantee that the list of statements will be executed at least once.)
  

  bool done = false;
  while( !done )
  {
      ProcessData();
      if( StopLooping() )
      {
          done = true;
      }
  }

Copyright (C) 2000-2005, The University of British Columbia