implemented Documentation of the first stage

README.md

@@ -4,9 +4,9 @@ Boost numerical data type for real numbers representation using range arithmetic
 ## Introduction
 
 ### The problem addressed by boost::real
-Several times, when dealing with complex mathematical calculus, numerical errors can be carried from one operation to the next and after several steps, the error may significantly increase obtaining a non trustworthy result. Normally, in these situations, the error is generated by the representation precision limit that truncate those numbers that does not fit in the representation precision generating errors without at least keeping track of the magnitude of the error. When this is the case, the real result is equal to the obtained approximated result plus the error (which is unknown).
+Several times, when dealing with complex mathematical calculus, numerical errors can be carried from one operation to the next and after several steps, the error may significantly increase obtaining a non-trustworthy result. Normally, in these situations, the error is generated by the representation precision limit that truncates those numbers that do not fit in the representation precision generating errors without at least keeping track of the magnitude of the error. When this is the case, the real result is equal to the obtained approximated result plus the error (which is unknown).
 
-Another mayor problem when dealing with real numbers is the irrational numbers representation as the number π or e<sup>π</sup>, they are not handled by the native number data types causing limitations when calculations are based on those numbers. Normally we define a truncation of those numbers that is good enough for our purposes, but many times, the needed precision depends on the operation made and the composition of those operation, therefore, we are unable to determine which is the correct precision until we run the programme.
+Another major problem when dealing with real numbers is the representation of the irrational number as the number π or e<sup>π</sup>, they are not handled by the native number data types causing limitations when calculations are based on those numbers. Normally we define a truncation of those numbers that are good enough for our purposes, but many times, the needed precision depends on the operation to do and to the composition of multiple operations, therefore, we are unable to determine which is the correct precision until we run the programme.
 
 ### The boost::real solution
 Boost::real is a real number representation data type that address the mentioned issues using range arithmetic [1] and defining the precision as dynamical to be determined in run-time. The main goal of this data type is to represent a real number "a" as a programme that returns a finite or infinite set of intervals a(k) = [m<sub>k</sub> - e<sub>k</sub>, m<sub>k</sub> + e<sub>k</sub>], K ∈ N ≥ 0, e<sub>k</sub> ≥ 0. Where K1 < K2 ⇒ a(k2) &sub; a(k1). For this purposes, any Boost::real number has a precision const iterator that iterates the set of intervals representing the number.
@@ -16,14 +16,14 @@ Also, to allow representing irrational numbers as π or e<sup>π</sup>, boost::r
 ## The boost::real numbers representation
 In boost::real, a number has one of the next three representations:
 
-    1. A number is a list of digits where the first ones are the integer part and the last ones are the fractional part. Where does the integer part ends and the fractional part starts is specified by an integer number.
+    1. A number is a list of digits where the first ones are the integer part and the last ones are the fractional part. To determine where the integer part ends and the fractional part starts, an integer is used to represent the number of integer digits.
     2. A number is an algorithm that one can ask what is the n-th digit and the algorithm will return that number.
     3. A number is a composition of two numbers related by an operator (+, -, *, /), the number creates pointers to the operands and each time the number is used, the operation is evaluated to return the result.
 
-Because of the third representation type, a number resulting of a complex calculus, is a binary tree where each internal vertex is an operation and the vertex children are its operands. The tree leaves are those numbers represented by either (1) or (2) while the internal vertex are those numbers represented by (3). More information of the used number representation can be found in [3]
+Because of the third representation type, a number resulting from a complex calculus is a binary tree where each internal vertex is an operation and the vertex children are its operands. The tree leaves are those numbers represented by either (1) or (2) while the internal vertex is those numbers represented by (3). More information about the used number representation can be found in [3]
 
 ## The boost::real precision iterator.
-The boost::real::const_precision_iterator is a forward iterator [4] that iterates through the number precision. The iterator returns two numbers, a lower and upper bound that represent the [m<sub>k</sub> - e<sub>k</sub>, m<sub>k</sub> + e<sub>k</sub>] limits of the number for a given precision. Each time the iterator is incremented, the interval range is decreased obtaining a new interval with a better precision. Normally, there is no need to interact with the precision iterator and it is used by the boost::real operators <<, < and >.
+The boost::real::const_precision_iterator is a forward iterator [4] that iterates through the number range precisions. The iterator returns two numbers, a lower and upper bound that represent the [m<sub>k</sub> - e<sub>k</sub>, m<sub>k</sub> + e<sub>k</sub>] limits of the number for a given precision. Each time the iterator is incremented, the interval range is decreased and a new interval with a better precision is obtained. Normally, there is no need to interact with the precision iterator and it is used by the boost::real operators <<, < and >.
 
 ## Interface
 
@@ -43,7 +43,7 @@ The boost::real::const_precision_iterator is a forward iterator [4] that iterate
 > Creates a copy of the number x, if the number is an operation, then, the constructor creates new copies of the x operands.
 
 > (4) **Default destructor** 
-> If the number is an operator, the destructor destroy its operands.
+> If the number is an operator, the destructor destroys its operands.
 
 ### Operators
 
@@ -53,13 +53,13 @@ The boost::real::const_precision_iterator is a forward iterator [4] that iterate
     4. bool operator<(const real& other) const
     5. std::ostream& operator<<(std::ostream& os, const boost::real& x)
 
-> (1) Creates a new boost::real number using the third representation. For this purpose, the operator creates copies of *this and x to use as the new real number operands and defines the + as the operation.
+> (1) Creates a new boost::real number using the third representation. For this purpose, the operator creates copies of *this and x to use as the new real number operands and defines the addition as the operation.
 
-> (2) Creates a new boost::real number using the third representation. For this purpose, the operator creates copies of *this and x to use as the new real number operands and defines the - as the operation.
+> (2) Creates a new boost::real number using the third representation. For this purpose, the operator creates copies of *this and x to use as the new real number operands and defines the subtraction as the operation.
 
 > (3) Uses the copy constructor to create a copy of x stored in *this
 
-> (4) Compares *this with x to check if *this is lower than x. This operator creates two precision iterators (one for each number) and iterates until the number ranges stop overlapping, when that happens, it compare the ranges bounds to determine if *this is less than x. **WARNING:** If *this is equal to x, then the ranges will always overlap, because of this, the operator uses a max precision limit and if that limit is reached, the operator throws a boost::real::precision_exception.
+> (4) Compares *this with x to check if *this is lower than x. This operator creates two precision iterators (one for each number) and iterates until the number ranges stop overlapping when that happens, it compares the ranges bounds to determine if *this is less than x. **WARNING:** If *this is equal to x, then the ranges will always overlap, because of this, the operator uses a max precision limit and if that limit is reached, the operator throws a boost::real::precision_exception.
 
 > (5) Creates a const_precision_iterator to print the number using the iterator << operator.
 
@@ -77,9 +77,9 @@ The boost::real::const_precision_iterator is a forward iterator [4] that iterate
     3. boost::real::const_precision_iterator(const boost::real::const_precision_iterator& x)
 
 > (1) ** Default constructor **
-> Create an empty iterator that does not points any number and thus, cannot yet be iterator.
+> Create an empty iterator that does not point any number and thus, cannot yet be iterated.
 
-> (2) Creates a iterator that points to the x number and iterates the number precision. If the number is deleted, the iterator behaviour is undefined.
+> (2) Creates an iterator that points to the x number and iterates the number precision. If the number is deleted, the iterator behaviour is undefined.
 
 > (3) ** Copy constructor ** 
 > Creates an iterator that points the same number than the x iterator does and is initialized in the same precision that x.
@@ -95,10 +95,68 @@ The boost::real::const_precision_iterator is a forward iterator [4] that iterate
 
 ## Examples
 
-
+```cpp
+#include <iostream>
+#include <real/real.hpp>
+
+int main() {
+    int i;
+    boost::real::real a,b,c,d,e,f,g,g2,h,j,k;
+
+    c = boost::real::real({9,9,9,9,9,9});
+    d = boost::real::real({9,9,9,9,9,9});
+    e = c + d;
+
+    std::cout << "c: " << c << std::endl;
+    std::cout << "d: " << d << std::endl;
+
+    boost::real::real::const_precision_iterator it = e.cbegin();
+    for(i = 0; i < 10; ++i) {
+        std::cout << "e iteration " << i <<": " << it << std::endl;
+        ++it;
+    }
+
+    f = boost::real::real({9,9,9,9,9,9});
+    g = boost::real::real({9,9,9,9,9,8});
+
+    if (g < f) {
+        std::cout << "g < f --> true" << std::endl;
+    } else {
+        std::cout << "g < f --> false" << std::endl;
+    }
+
+    h = f - g;
+
+    std::cout << "f: " << f << std::endl;
+    std::cout << "g: " << g << std::endl;
+    std::cout << "h: " << h << std::endl;
+
+    return 0;
+}
+```
+
+### Output
+```cpp
+c: 0.99999900
+d: 0.99999900
+e iteration 0: [1.98, 2.00]
+e iteration 1: [1.998, 2.000]
+e iteration 2: [1.9998, 2.0000]
+e iteration 3: [1.99998, 2.00000]
+e iteration 4: 1.999998
+e iteration 5: 1.999998
+e iteration 6: 1.999998
+e iteration 7: 1.999998
+e iteration 8: 1.999998
+e iteration 9: 1.999998
+g < f --> true
+f: 0.999999
+g: 0.999998
+h: 0.000001
+```
 
 ## References
     1. Computable calculus / Oliver Aberth, San Diego : Academic Press, c2001
     2. Lambov, B. (2007). RealLib: An efficient implementation of exact real arithmetic. Mathematical Structures in Computer Science, 17(1), 81-98.
     3. Aberth, O., & Schaefer, M. J. (1992). Precise computation using range arithmetic, via C++. ACM Transactions on Mathematical Software (TOMS), 18(4), 481-491.
-    4. https://en.cppreference.com/w/cpp/concept/ForwardIterator
+    4. https://en.cppreference.com/w/cpp/concept/ForwardIterator