|
CGAL 5.2.4 - IO Streams
|
All classes in the CGAL kernel provide input and output operators for IO streams. Classes external to CGAL are also supported, by means of oformat() (Section IO for Non CGAL Types). The basic task of such an operator is to produce a representation of an object that can be written as a sequence of characters on devices as a console, a file, or a pipe. In CGAL we distinguish between a raw ascii, a raw binary and a pretty printing format.
In ASCII mode, objects are written as a set of numbers, e.g. the coordinates of a point or the coefficients of a line, in a machine independent format. In BINARY mode, data are written in a binary format, e.g. a double is represented as a sequence of four byte. The format depends on the machine. The mode PRETTY serves mainly for debugging as the type of the geometric object is written, as well as the data defining the object. For example for a point at the origin with Cartesian double coordinates, the output would be PointC2(0.0, 0.0). At the moment CGAL does not provide input operations for pretty printed data. By default a stream is in Ascii mode.
CGAL provides the following functions to modify the mode of an IO stream.
The following functions allow to test whether a stream is in a certain mode.
CGAL defines output operators for classes that are derived from the class ostream. This allows to write to ostreams as std::cout or std::cerr, as well as to std::ostringstream and std::ofstream. The output operator is defined for all classes in the CGAL Kernel and for the class Color as well. Let os be an output stream.
CGAL defines input operators for classes that are derived from the class istream. This allows to read from istreams as std::cin, as well as from std::istringstream and std::ifstream. The input operator is defined for all classes in the CGAL Kernel. Let is be an input stream.
To ensure that non-CGAL types are formatted correctly (i.e., respecting IO::Mode), oformat() can be used. For types with a Output_rep specialization, the respective output routine of Output_rep will be called by oformat(). Otherwise, the stream output operator will be called.
Optional, you can provide a second template parameter F as a formatting tag:
For a list of formatting tags supported by the type T, please refer to the documentation of the respective type.
In some situations, you want to control the output formatting for a type T. For external types (third party libraries etc.), there might be problems if their stream output operator does not respect IO::Mode. The purpose of Output_rep is to provide a way to control output formatting that works independently of the object's stream output operator.
Instead of putting T directly into an output stream, T is wrapped into an output representation Output_rep. For convenience, a function oformat() exists which constructs an instance of Output_rep.
If you do not specialize Output_rep for T, T's stream output operator is called from within Output_rep, by default. If you want another behaviour for your type T, you have to provide a specialization for that type. Furthermore, you can provide specializations with a second template parameter (a formatting tag). The second template parameter defaults to Null_tag and means default behaviour.
For example, specializing Output_rep for CORE::BigRat (without a formatting tag parameter) could look like this:
An object of the class Color is a color available for drawing operations in many CGAL output streams.
Each color is defined by a triple of integers (r,g,b) with 0 \( \le \) r,g,b \( \le \) 255, the so-called rgb-value of the color. There are a 11 predefined Color functions available: black(), white(), gray(), red(), green(), deep_blue(), blue(), purple(), violet(), orange(), and yellow().
Three classes are provided by CGAL as adaptors to input and output stream iterators. The class Istream_iterator is an input iterator adaptor and is particularly useful for classes that are similar but not compatible to std::istream. Similarly, the class Ostream_iterator is an output iterator adaptor. The class Verbose_ostream can be used as an output stream. The stream output operator << is defined for any type. The class stores in an internal state a stream and whether the output is active or not. If the state is active, the stream output operator << uses the internal stream to output its argument. If the state is inactive, nothing happens.
WKT stands for Well Known Text and it is a text markup language for representing vector geometry objects on a geographical map. See the wikipedia page for details. CGAL supports a subset of WKT types: point, multipoint, linestring, multilinestring, polygon and multipolygon. Free functions are provided for reading and writing several CGAL types in those WKT types, namely:
CGAL::Point_2CGAL::Point_3CGAL::Polygon_with_holes_2In case you have to read data in a simple xml file with a simple structure, without existing I/O libraries the boost::property_tree comes in handy. The following small example shows how to parse a file looking like this:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PolySet>
<Polygon>
<Point X="-715.8811978465" Y="-2729.9490000000" Z="-534.9000000000"/>
<Point X="-718.1905989232" Y="-2729.9490000000" Z="-538.9000000000"/>
<Point X="-722.8094010768" Y="-2729.9490000000" Z="-538.9000000000"/>
</Polygon>
</PolySet>
File Stream_support/read_xml.cpp
1.8.13