added docu for oformat/Output_rep (similarly for input)

iostream/doc_tex/IOstream/IOstream.tex

@@ -2,19 +2,19 @@
 All classes in the \cgal\ kernel provide input and output operators for
 IO streams.  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. 
+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.
 
 \ccEnum{enum Mode {ASCII = 0, BINARY, PRETTY};}{}
 
 
 In \ccc{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. 
+the coefficients of a line, in a machine independent format.
 In \ccc{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. 
+as a sequence of four byte. The format depends on the machine.
 The mode  \ccc{PRETTY}
 serves mainly for debugging as the type of the geometric
 object is written, as well as the data defining the object. For example
@@ -58,7 +58,7 @@ 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 \ccStyle{ostream}. This allows to write to ostreams
 as \ccStyle{cout} or \ccStyle{cerr}, as well as to strstreams
-and fstreams. 
+and fstreams.
 The output operator is defined for all classes in the \cgal\ kernel and for the class \ccc{Color} as well.
 Let \ccc{os}  be an output stream.
 
@@ -94,8 +94,8 @@ int main()
 
     return 1;
 }
-\end{cprog} 
-%\end{ccClass} 
+\end{cprog}
+%\end{ccClass}
 
 
 %\newpage
@@ -111,12 +111,12 @@ The input operator is defined for all classes in the \cgal\ kernel.
 Let \ccc{is} be an input stream.
 
 \ccFunction{istream& operator>>(istream& is, Class c);}
-   {Extracts object \ccStyle{c} from the stream \ccc{is}. Returns \ccc{is}.} 
+   {Extracts object \ccStyle{c} from the stream \ccc{is}. Returns \ccc{is}.}
 
 
 \ccExample
 
-\begin{cprog}
+\begin{ccExampleCode}
 
 #include <CGAL/basic.h>
 #include <iostream>
@@ -143,8 +143,8 @@ main()
 
     return 1;
 }
-\end{cprog} 
-%\end{ccClass} 
+\end{ccExampleCode}
+%\end{ccClass}
 
 
 

iostream/doc_tex/IOstream_ref/Input_rep.tex

@@ -0,0 +1,9 @@
+\begin{ccRefClass}{Input_rep<T,F>}
+
+\ccDefinition
+
+The definition of \ccc{Input_rep} is completely symmetric to \ccc{Output_rep}.
+
+
+
+\end{ccRefClass}

iostream/doc_tex/IOstream_ref/Output_rep.tex

@@ -0,0 +1,54 @@
+\begin{ccRefClass}{Output_rep<T,F>}
+
+\ccDefinition
+
+In some situations, you want to control the output formatting for a type \texttt{T}. For external types (third party libraries etc.), there might be problems if the stream output operator does not honor the CGAL output mode. The purpose of \ccc{Output_rep} is to provide a way to control output formatting that works independently of the object's stream output operator.
+
+\ccc{Output_rep} is used in conjunction with the free function \ccc{oformat}. Both provide an intermediate layer between the actual output stream and the type \texttt{T}. \ccc{Output_rep<T>} can be regarded as a wrapper around \texttt{T} and \ccc{oformat} is just a convenience function to construct an instance of \ccc{Output_rep<T>}.
+
+By default, the object's stream output operator is called. If you want another behaviour for your type \texttt{T}, you have to create a template specialization for that type. Furthermore, you can provide specializations with a second template parameter (a formatting tag). The second template parameter defaults to \ccc{Null_tag}.
+
+Specializations of \ccc{Output_rep} should provide the following features:
+
+\begin{ccExampleCode}
+template< class F >
+struct Output_rep< My_special_type, F > {
+    Output_rep( const My_special_type& t );
+    std::ostream& operator()( std::ostream& out ) const;
+};
+\end{ccExampleCode}
+
+
+
+\ccExample
+For example, if you want special formatting for \ccc{CORE::BigRat}, your \ccc{Output_rep} specialization could look like this:
+\begin{ccExampleCode}
+template <class F>
+class Output_rep< ::CORE::BigRat, F> {
+    const ::CORE::BigRat& t;
+public:
+    Output_rep( const ::CORE::BigRat& tt) : t(tt) {}
+
+    std::ostream& operator()( std::ostream& out) const {
+        switch (get_mode(out)) {
+        case IO::PRETTY:{
+            if(CGAL_CORE_DENOMINATOR(t) == ::CORE::BigRat(1))
+                return out <<CGAL_CORE_NUMERATOR(t);
+            else
+                return out << CGAL_CORE_NUMERATOR(t)
+                           << "/"
+                           << CGAL_CORE_DENOMINATOR(t);
+            break;
+        }
+
+        default:
+            return out << CGAL_CORE_NUMERATOR(t)
+                       << "/"
+                       << CGAL_CORE_DENOMINATOR(t);
+        }
+    }
+};
+\end{ccExampleCode}
+
+
+\end{ccRefClass}

iostream/doc_tex/IOstream_ref/iformat.tex

@@ -0,0 +1,5 @@
+\begin{ccRefFunction}{iformat}
+
+The definition of the function \ccc{iformat} is completely symmetric to \ccc{oformat}.
+
+\end{ccRefFunction}

iostream/doc_tex/IOstream_ref/intro.tex

@@ -3,7 +3,7 @@
 % +------------------------------------------------------------------------+
 % | 10 04 2002   Mariette Yvinec
 % | Package: iostream
-% | 
+% |
 % |
 % | %RefPage: end of header, begin of main body
 % +------------------------------------------------------------------------+
@@ -35,13 +35,17 @@ the printing mode.
 \ccRefIdfierPage{CGAL::set_binary_mode} \\
 \ccRefIdfierPage{CGAL::set_pretty_mode} \\
 \ccRefIdfierPage{CGAL::operator>>} \\
-\ccRefIdfierPage{CGAL::operator<<} 
+\ccRefIdfierPage{CGAL::operator<<} \\
+\ccRefIdfierPage{CGAL::iformat} \\
+\ccRefIdfierPage{CGAL::oformat}
 
 \subsection*{Classes}
 
 \ccRefIdfierPage{CGAL::Istream_iterator<T,Stream>}\\
 \ccRefIdfierPage{CGAL::Ostream_iterator<T,Stream>}\\
-\ccRefIdfierPage{CGAL::Verbose_ostream}
+\ccRefIdfierPage{CGAL::Verbose_ostream}\\
+\ccRefIdfierPage{CGAL::Input_rep<T,F>}\\
+\ccRefIdfierPage{CGAL::Output_rep<T,F>}
 
 
 

iostream/doc_tex/IOstream_ref/main.tex

@@ -16,6 +16,10 @@
 \input{IOstream_ref/Mode.tex}
 \input{IOstream_ref/Ostream_iterator.tex}
 \input{IOstream_ref/output_operator.tex}
+\input{IOstream_ref/Input_rep.tex}
+\input{IOstream_ref/Output_rep.tex}
+\input{IOstream_ref/iformat.tex}
+\input{IOstream_ref/oformat.tex}
 \input{IOstream_ref/set_ascii_mode.tex}
 \input{IOstream_ref/set_binary_mode.tex}
 \input{IOstream_ref/set_mode.tex}

iostream/doc_tex/IOstream_ref/oformat.tex

@@ -0,0 +1,17 @@
+\begin{ccRefFunction}{oformat}
+
+\ccc{Output_rep} is used in conjunction with the free function \ccc{oformat}. Both provide an intermediate layer between the actual output stream and the type \texttt{T}. \ccc{Output_rep<T>} can be regarded as a wrapper around \texttt{T} and \ccc{oformat} is just a convenience function to construct an instance of \ccc{Output_rep<T>}.
+
+\ccFunction{template <class T> Output_rep<T> oformat( const T& t);}
+           {generic IO output format manipulator.}
+
+\ccFunction{template <class T, typename F> Output_rep<T,F> oformat( const T& t, F );}
+           {generic IO output format manipulator with formatting tag.}
+
+\ccExample
+\begin{ccExampleCode}
+std::cout << CGAL::oformat( myobject );
+\end{ccExampleCode}
+
+
+\end{ccRefFunction}