diff --git a/iostream/doc_tex/IOstream/IOstream.tex b/iostream/doc_tex/IOstream/IOstream.tex index 934fe24c1f6..73e1c267729 100644 --- a/iostream/doc_tex/IOstream/IOstream.tex +++ b/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 #include @@ -143,8 +143,8 @@ main() return 1; } -\end{cprog} -%\end{ccClass} +\end{ccExampleCode} +%\end{ccClass} diff --git a/iostream/doc_tex/IOstream_ref/Input_rep.tex b/iostream/doc_tex/IOstream_ref/Input_rep.tex new file mode 100644 index 00000000000..ccf282ec880 --- /dev/null +++ b/iostream/doc_tex/IOstream_ref/Input_rep.tex @@ -0,0 +1,9 @@ +\begin{ccRefClass}{Input_rep} + +\ccDefinition + +The definition of \ccc{Input_rep} is completely symmetric to \ccc{Output_rep}. + + + +\end{ccRefClass} \ No newline at end of file diff --git a/iostream/doc_tex/IOstream_ref/Output_rep.tex b/iostream/doc_tex/IOstream_ref/Output_rep.tex new file mode 100644 index 00000000000..dea3a2c2b76 --- /dev/null +++ b/iostream/doc_tex/IOstream_ref/Output_rep.tex @@ -0,0 +1,54 @@ +\begin{ccRefClass}{Output_rep} + +\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} 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}. + +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 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 <>} \\ -\ccRefIdfierPage{CGAL::operator<<} +\ccRefIdfierPage{CGAL::operator<<} \\ +\ccRefIdfierPage{CGAL::iformat} \\ +\ccRefIdfierPage{CGAL::oformat} \subsection*{Classes} \ccRefIdfierPage{CGAL::Istream_iterator}\\ \ccRefIdfierPage{CGAL::Ostream_iterator}\\ -\ccRefIdfierPage{CGAL::Verbose_ostream} +\ccRefIdfierPage{CGAL::Verbose_ostream}\\ +\ccRefIdfierPage{CGAL::Input_rep}\\ +\ccRefIdfierPage{CGAL::Output_rep} diff --git a/iostream/doc_tex/IOstream_ref/main.tex b/iostream/doc_tex/IOstream_ref/main.tex index 53198b94cda..ed0c9421fcd 100644 --- a/iostream/doc_tex/IOstream_ref/main.tex +++ b/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} diff --git a/iostream/doc_tex/IOstream_ref/oformat.tex b/iostream/doc_tex/IOstream_ref/oformat.tex new file mode 100644 index 00000000000..5405918e25c --- /dev/null +++ b/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} 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}. + +\ccFunction{template Output_rep oformat( const T& t);} + {generic IO output format manipulator.} + +\ccFunction{template Output_rep 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} \ No newline at end of file