NOTES ABOUT THE TRANSLATION OF C++ CODE TO JAVA
------------------------------------------------

** Inline functions

Inline functions in C++ have no Java equivalent.  In Java, there is no
distinction between header file (.h) and implementation file (.cc/.cpp); all
the code is written in a single file (.java).  That is, at the same time a
method is declared, its implementation is provided (body of the method). 
However, this does not mean that the method is inline.  The compiler never
generates 'inline' code for methods, although it does so for certain 'final
static' constants with primitive types.  It is the JVM (Java Virtual
Machine), specifically the JIT compiler, which, at runtime, may decide to
generate inline code for a method based on a complex analysis of the code to
be executed.

** Pointers and references

Notice how pointers to objects in C++ are equivalent to Java references,
although syntactically they are used in a different way: pointers are
declared with '*', whereas references are not.  When using pointers in C++,
you must use the '->' operator to refer to the properties of the object it
points to, whereas in Java you must use the '.' operator:

C++                              Java
   SomeClass * aPointer;            SomeClass aReference;            // Creation of pointer/reference
   aPointer = new SomeClass();      aReference = new SomeClass();    // Creation of the objet (¡at run time!)
   aPointer->attribute = ...        aReferene.attribute = ...    // Access to an attribute (provided that it is visible)
   aPointer->method();              aReference.method();         // Call to a class method

** Arrays of unknown size

In C++ one can define arrays whose dimension is only known at execution time
as follows:

	int* array;
	int dimension;

'array' will point to a memory area that we will be allocated with 'new' and that
will have as many components as the 'dimension' variable indicates. Note that
we need to save the size of the array in the variable 'dimension' because,
after allocating the memory, we will need to know how many components the array
has in order to not go over it and cause a segmentation fault.

Let us suppose that during the execution of the program we need to create an array
of 10 integers. We will make

	dimension = 10;
	array = new int[10];

and use it as follows:

	for (int i=0; i<dimension; i++) array[i] = i;

In Java this is the default behaviour for arrays: it allocates memory
at runtime with 'new'. A code in Java which is equivalent to C++ code above follows:

declaration:

	int[] array;

allocation of memory for the array at runtime:

	array = new int[10];

Note an important difference: the variable 'dimension' is not needed.
Java arrays (which are actually objects!), have an attribute 'length'
which is initialised to the size of the array and can bee consulted
whenever needed:

	for (int i=0; i<array.length; i++) array[i] = i;

** Friend functions

There are no friend functions in Java either.  For a class to access to
certain properties of another class, a mechanism known as 'package
visibility' is used; we will see it later.

** Use of 'const' in C++ ('final' in Java)

In Java there is no 'const' keyword, 'final' is used instead.  Notice that
'final' has some uses other than 'const' in C++.  In the specific case of
references to objects in C++, as in the case of the Coordinate copy
constructor, in Java we will simply provide a Coordinate argument:

C++                                 Java
    Coordinate(const Coordinate& l);        Coordinate(Coordinate c) {...}

** Overloaded operators in C++

In Java there is no operator overloading; therefore, overloaded operators in
C++ (such as operator>>) should be implement as regular methods (in this
case, the output operator equals the toString() method).

In C++ header files, when declaring a method (member function) it is not
compulsory to indicate the name of the arguments (as in 'void
setX(double)'), only their type.  This is not possible in Java, as we have
to define the body of the method afterwards!

The method 'operator==' is roughly equivalent to the 'equals()' method in
Java.  Both have the mission to tell us if two objects are equal, that is,
if they contain the same values in the attributes that describe their state. 
The difference lies in the type of argument of both methods.  In the C++
version, it is a reference to an object of the same class for which we
define the operator (Coordinate), whereas in Java it is a reference to Object. 
This implies among other things that, when implementing the equals() method,
we first have to check if the object that is passed as an argument is of the
same class for which we define equals().

Note that operators '+', -' in C++ have two peculiarities

1.  Operation 'a + b' is equivalent to 'a.operator+(b)' and its result is
a new object equal to the sum of a and b.    Same happens with
'-'.

2.  These operators have associativity on the right, which means that we can
write

	a + b - c;

which is equivalent to

	a.operator+( b.operator-(c) );

In fact, we could have wrotten it as in the previous line, but obviously 'a+b-c' is much 
more compact and easy to understand for us humans.

The previous expression is, in turn, equivalent to 

	a + (b - c);
	
(b - c) returns a new object, which is used as the argument to operator+(), which in turn 
will create a new object that equals the sum of 'a' and the object '(b-c)'. Neither of  
'a', 'b', and 'c' are altered during these operations.

Java does not support operator overloading. Methods equivalent to
C++ addition and subtraction in Java ('add()' and 'substract()' in Coordinate class UML diagram),
behave similarly to operator+() and operator-(), with one difference:
associativity is given by the operator '.', whose associativity is
left to right, so writing in Java

	a.add(b).substract(c);

is equivalent to 

	(a + b) - c;

in C++, where a, b and c are objects of type Coordinate. If we want to obtain right to 
left associativity, we should write:

C++:
	a + b - c; // equals 'a + (b - c)', i. e., 'a.operator+(b.operator-(c))'

Java:
	a.add(b.substract(c));


** Simple I/O: 

The equivalent to the input/output instructions in C++,

	cout << ... << endl; 
	cerr << ... << endl;

in Java are

	System.out.println(...); // Standard output
	System.err.println(...); // Standard error
 
For example, in C++,

	cout << "Welcome, visitor number" << num_visitor << "!" << endl;

is translated to Java as

	System.out.println("Welcome, visitor number" + num_visior + "!");

Operator '+' acts here as a string concatenator.  'num_visitor', which is
presumably a number, is first converted into a string and then concatenated;
this is done in a way transparent to the programmer.

