.. _BasicPointers1:

.. raw:: html

   <script>ODSA.SETTINGS.DISP_MOD_COMP = true;ODSA.SETTINGS.MODULE_NAME = "BasicPointers1";ODSA.SETTINGS.MODULE_LONG_NAME = "Basic References Part 1";ODSA.SETTINGS.MODULE_CHAPTER = "Introduction to Pointers in Java"; ODSA.SETTINGS.BUILD_DATE = "2020-01-15 11:42:24"; ODSA.SETTINGS.BUILD_CMAP = true;JSAV_OPTIONS['lang']='en';JSAV_EXERCISE_OPTIONS['code']='java';</script>


.. |--| unicode:: U+2013   .. en dash
.. |---| unicode:: U+2014  .. em dash, trimming surrounding whitespace
   :trim:



.. odsalink:: AV/Pointers/num42CON.css

.. odsalink:: AV/Pointers/employeeEmpRefCON.css

.. odsalink:: AV/Pointers/empRefnullCON.css

.. odsalink:: AV/Pointers/empRefsecondCON.css
.. This file is part of the OpenDSA eTextbook project. See
.. http://algoviz.org/OpenDSA for more details.
.. Copyright (c) 2012-2016 by the OpenDSA Project Contributors, and
.. distributed under an MIT open source license.

.. avmetadata::
   :author: Nick Parlante, Cliff Shaffer, Sally Hamouda, Mostafa Mohammed, and Sushma Mandava
   :requires:
   :satisfies: Pointer intro
   :topic: Pointers


Basic References Part 1
=======================

Pointers and References
-----------------------

What is a Pointer?
~~~~~~~~~~~~~~~~~~

There's a lot of nice, tidy code you can write without knowing about
:term:`pointers <pointer>`.
But once you learn to use the power of pointers, you can never go
back.
There are too many things that can only be done with pointers.
But with increased power comes increased responsibility.
Pointers allow new and more ugly types of bugs, and pointer bugs can
crash in random ways which makes them more difficult to debug.
Nonetheless, even with their problems, pointers are an irresistibly
powerful programming construct.

Pointers solve two common software problems.
First, pointers allow different sections of code to share information
easily.
You can get the same effect by copying information back and forth, but
pointers solve the problem better.
Second, pointers enable complex linked data structures like
:term:`linked lists <linked list>` and
:term:`binary trees <binary tree>`.


What is a Reference?
~~~~~~~~~~~~~~~~~~~~

Java actually uses a restricted version of the pointer concept,
which is called a :term:`reference`.
While they mean roughly the same thing, the term "pointer" tends to be
used in discussions that are not specific to any particular language
or implementation.
The word "pointers" connotes the common C/C++ implementation of
pointers as :term:`addresses <address>` or locations in memory.
Programmers have more limited access with a reference.
This limits what they can do, but the Java philosophy is that this is
more than made up for by a greater chance of the code working correctly.
Essentially, Java programmers may only assign to a reference and
compare two references for equality.
Other uses of a reference are done implicitly with no control from the
programmer.
These restrictions reduce the chance for bugs.


Data Types in Java
------------------

Simple ``int`` and ``float`` variables operate pretty intuitively.
An ``int`` variable is like a box that can store a single ``int``
value such as 42.
Visually, a simple variable can be viewed as a box with its current
value shown inside.

.. _num42Fig:

.. inlineav:: num42CON dgm
   :align: center

A reference variable works a little differently.
It does not store a simple value directly.
Instead, a reference variable stores a :term:`reference` to some
:term:`object`.
The object that the reference refers to is sometimes known as its
:term:`pointee`.
In the next figure, the reference variable (called ``empRef``) is
shown as a box that contains the beginning of a directed line, which
leads to its pointee (an ``Employee`` object, shown as the box storing
two fields: the string value "John" and the integer value "1000").
So ``empRef`` is the reference and the ``Employee`` object is its
pointee.
What is stored inside of ``empRef``?
Its value is **not** an ``Employee`` object.
Its value is only a reference to an ``Employee`` object.
(By the way, there is no commonly used word for the concept of a
pointee |---| pointee is just the word that we used in these
explanations.)

.. inlineav:: employeeEmpRefCON dgm
   :align: center

Going back to simple things like ``int`` and ``float`` variables that
just store a value in a box:
In Java, these are referred to as
:term:`primitive data types <primitive data type>`.
In Java, Objects and Arrays are non-primitive data types,
and they are always accessed by references.
Java automatically uses references behind the scenes for such complex
types, and there is no reference-specific syntax (like there is in C/C++).
You just need to realize that assignment operations like
``a = b`` will automatically be implemented with references if ``a`` and
``b`` are arrays or objects,
**which is different from the behavior that you get if** ``a`` **and**
``b`` **are primitive objects like int**.
Assignments and parameters with arrays and objects are intrinsically
shallow or shared |---|, which is discussed in the Shallow vs. Deep
Copying section below.


Referencing and Dereferencing
-----------------------------

:term:`Dereferencing <dereference>` means to follow a reference to get
the value of its pointee.
Dereferencing ``empRef`` in the figure above gives back its pointee, the
``Employee`` object.
So, "dereference" just means to access the value of the pointee.
Visually, the result of a dereference is the object pointed to by the
arrow.
In Java, this most often is done with the "dot" operator to access a
field or method of an object.
For example::

   String myName = empRef.name()

This will dereference ``empRef`` to call the ``name`` method for that
object.

The key restriction is that the reference must have a pointee to access.
A lot of bugs in reference code involve violating that one
restriction, which results in the ever-popular ``NullPointerException``.
A reference must be assigned a pointee before dereference operations
will work.

The constant ``null`` is a special reference value that encodes the
idea of "points to nothing".
It turns out to be convenient to have a well-defined reference value
to represent the idea that a reference does not have a pointee.
It is a runtime error to try to get the pointee of a ``null``
reference.
In drawings, the value ``null`` is often drawn as X's or as a diagonal
line between the corners of the reference variable's box.

.. _numptrnullFig:

.. inlineav:: empRefnullCON dgm
   :align: center


changePointeeDataDirect
-----------------------

.. extrtoolembed:: 'changePointeeDataDirect'
   :module: BasicPointers1
   :long_name: changePointeeDataDirect
   :learning_tool: code-workout
   :launch_url: https://opendsa-server.cs.vt.edu/lti/launch_extrtool/182705
   :id: 108703



The Employee Class
------------------

We are going to use the ``Employee`` object for a lot of our examples,
so let's make a formal introduction now.
Meet the ``Employee`` class.

.. codeinclude:: Pointers/PointerExample
   :tag: EmployeeClass


Reference Assignments
---------------------

An assignment (``=``) of one reference to another makes them point to
the same pointee.
It's a simple rule for a potentially complex situation, so it is worth
repeating: assigning one reference to another makes them point to the
same thing.
The example below adds a second reference, named ``second``, assigned
with the statement::

   second = empRef;

The result is that ``second`` points to the same pointee as
``empRef``.
In the drawing, this means that the ``second`` and ``empRef`` boxes
both contain arrows pointing to the ``Employee`` object.
Assignment between references does not change or even touch the
pointees.
It just changes which pointee a reference refers to.

.. _numptrsecondlFig:

.. inlineav:: empRefsecondCON dgm
   :align: center

After the assignment, testing for ``(second == empRef)`` would return
true.

The assignment operation also works with the ``null`` value.
An assignment operation with a ``null`` reference copies the ``null``
value from one reference to another.

Memory drawings are key to thinking about reference code.
When you are looking at code, think about how it will use memory at
run time, then make a quick drawing to work out your ideas.
This tutorial uses a lot of drawings to show how references work.
You should too.


circularList1
-------------

.. extrtoolembed:: 'circularList1'
   :module: BasicPointers1
   :long_name: circularList1
   :learning_tool: code-workout
   :launch_url: https://opendsa-server.cs.vt.edu/lti/launch_extrtool/182707
   :id: 108706


.. odsascript:: AV/Pointers/num42CON.js
.. odsascript:: AV/Pointers/employeeEmpRefCON.js
.. odsascript:: AV/Pointers/empRefnullCON.js
.. odsascript:: AV/Pointers/empRefsecondCON.js