mirror of https://github.com/CGAL/cgal
117 lines
4.3 KiB
Plaintext
117 lines
4.3 KiB
Plaintext
/*!
|
|
|
|
\page introduction Hello World
|
|
\autotoc
|
|
|
|
\author %CGAL Editorial Board
|
|
|
|
The goal of this chapter is to get a first idea of the look and feal of a program that uses CGAL.
|
|
|
|
We will take a closer look at three \cgal example
|
|
programs, all of them computing the 2D convex hull of a set of points.
|
|
|
|
|
|
Points in a Built-in Array
|
|
==========================
|
|
|
|
In the first example we have an array of five points.
|
|
As the convex hull of these points is a subset of the input
|
|
it is safe to provide an array for storing the result which
|
|
has the same size.
|
|
|
|
\cgalexample{Convex_hull_2/array_convex_hull_2.cpp}
|
|
|
|
|
|
All \cgal header files are in the subdirectory `include/CGAL`. All \cgal
|
|
classes and functions are in the namespace `CGAL`. The geometric
|
|
primitives, like the point type, are defined in a kernel. \cgal comes
|
|
with several kernels, and as the convex hull algorithm only makes
|
|
comparisons of coordinates and orientation tests of input points,
|
|
we can choose a kernel that provides exact predicates, but no
|
|
exact geometric construction.
|
|
|
|
The convex hull function takes three arguments, the start
|
|
and past-the-end pointer for the input, and the start pointer of the
|
|
array for the result. The function returns the pointer
|
|
into the result array just behind the last convex hull
|
|
point written, so the pointer difference tells us how
|
|
many points are on the convex hull.
|
|
|
|
|
|
Points in a STL %Vector
|
|
======================
|
|
|
|
In the second example we replace the built-in array
|
|
by a `std::vector` of the Standard Template Library.
|
|
|
|
\cgalexample{Convex_hull_2/vector_convex_hull_2.cpp}
|
|
|
|
We put some points in the vector calling the `push_back()`
|
|
method of the `std::vector` class.
|
|
|
|
We then call the convex hull function. The first two arguments,
|
|
`points.begin()` and `points.end()` are *iterators*, which are a
|
|
generalization of pointers: they can be dereferenced and
|
|
incremented. The convex hull function is *generic* in the sense
|
|
that it takes as input whatever can be dereferenced and incremented.
|
|
|
|
The third argument is where the result gets written to. In the
|
|
previous example we provided a pointer to allocated memory. The
|
|
generalization of such a pointer is the *output iterator*, which
|
|
allows to increment and assign a value to the dereferenced iterator.
|
|
In this example we start with an empty vector which grows as needed.
|
|
Therefore, we cannot simply pass it `result.begin()`, but an output
|
|
iterator generated by the helper function
|
|
`std::back_inserter(result)`. This output iterator does nothing when
|
|
incremented, and calls `result.push_back(..)` on the assignment.
|
|
|
|
Points in Streams
|
|
=================
|
|
|
|
The last example program reads a sequence of points from standard
|
|
input `std::cin` and writes the points on the convex hull to standard
|
|
output `std::cout`.
|
|
|
|
Instead of storing the points in a container such as an `std::vector`,
|
|
and passing the begin/end iterator of the vector to the convex hull
|
|
function, we use helper classes that turn file pointers into
|
|
iterators.
|
|
|
|
\cgalexample{Convex_hull_2/iostream_convex_hull_2.cpp}
|
|
|
|
In the example code you see input and output stream iterators
|
|
templated with the point type. A `std::istream_iterator<Point_2>`
|
|
hence allows to traverse a sequence of objects of type `Point_2`, which
|
|
come from standard input as we pass `std::cin` to the
|
|
constructor of the iterator. The variable `input_end` denotes
|
|
end-of-file.
|
|
|
|
A `std::ostream_iterator<Point_2>` is an output iterator, that is an
|
|
iterator to which, when dereferenced, we can assign a value. When
|
|
such an assignment to the output iterator happens somewhere inside the
|
|
convex hull function, the iterator just writes the assigned point to
|
|
standard output, because the iterator was constructed with
|
|
`std::cout`.
|
|
|
|
The call to the convex hull function takes three arguments, the input
|
|
iterator range, and the output iterator to which the result gets
|
|
written.
|
|
|
|
If you know the \stl, the Standard Template Library, the above makes
|
|
perfect sense, as this is the way the \stl decouples algorithms from
|
|
containers. If you don't know the \stl, you maybe better first
|
|
familiarize yourself with its basic ideas.
|
|
|
|
Further Reading
|
|
===============
|
|
|
|
We also recommend the standard text books by
|
|
Josuttis \cite cgal:j-csl-99, or Austern \cite cgal:a-gps-98 for the
|
|
\stl and its notion of *concepts* and *models*.
|
|
|
|
Other resources for \cgal are the tutorials at
|
|
http://www.cgal.org/Tutorials/ and the user support page at
|
|
http://www.cgal.org/.
|
|
|
|
*/
|