CGAL 6.2 - IO Streams: Reference Manual

CGAL 6.2 - IO Streams

Loading...
Searching...
No Matches
Modules | Classes | Typedefs | Functions
Reference Manual

##

Andreas Fabri, Geert-Jan Giezeman, and Lutz Kettner
All classes in the CGAL kernel provide input and output operators for I/O 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.
Introduced in: CGAL 1.0
BibTeX: cgal:fgk-ios-12-26a
License: LGPL

All classes in the CGAL kernel provide input and output operators for I/O streams. CGAL provides three different printing mode, defined in the enum `IO::Mode` , as well as different functions to set and get the printing mode.

## Classified Reference Pages

## Enum

- `CGAL::IO::Mode`
- `CGAL::IO::Ansi_color`

## Classes

- `CGAL::IO::Color`
- `CGAL::IO::Basic_color_streambuf<CharT,Traits>`
- `CGAL::IO::Color_streambuf`
- `CGAL::IO::Color_wstreambuf`
- `CGAL::IO::Basic_color_stream_guard<StreamT>`
- `CGAL::IO::Color_stream_guard`
- `CGAL::IO::Color_wstream_guard`
- `CGAL::IO::Basic_indenting_streambuf<CharT,Traits>`
- `CGAL::IO::Indenting_streambuf`
- `CGAL::IO::Indenting_wstreambuf`
- `CGAL::IO::Basic_indenting_stream_guard<StreamT>`
- `CGAL::IO::Indenting_stream_guard`
- `CGAL::IO::Indenting_wstream_guard`
- `CGAL::Istream_iterator<T,Stream>`
- `CGAL::Ostream_iterator<T,Stream>`
- `CGAL::Verbose_ostream`
- `CGAL::Input_rep<T,F>`
- `CGAL::Output_rep<T,F>`

## Functions

- `CGAL::IO::make_color_guards()`
- `CGAL::IO::stream_supports_color()`
- `CGAL::IO::make_indenting_guards()`
- `CGAL::IO::get_mode()`
- `CGAL::IO::is_ascii()`
- `CGAL::IO::is_binary()`
- `CGAL::IO::is_pretty()`
- `CGAL::IO::set_mode()`
- `CGAL::IO::set_ascii_mode()`
- `CGAL::IO::set_binary_mode()`
- `CGAL::IO::set_pretty_mode()`
- `CGAL::operator>>()`
- `CGAL::operator<<()`
- `CGAL::IO::iformat()`
- `CGAL::IO::oformat()`

## I/O Functions

- `CGAL::IO::read_polygon_soup()`
- `CGAL::IO::write_polygon_soup()`
- I/O for STL files
- I/O for PLY files
- I/O for OBJ files
- I/O for OFF files
- I/O for GOCAD files
- I/O for VTK files
- I/O for 3MF files
- I/O for WKT files
- I/O for LAS files
- I/O for XYZ files

## Modules
| Stream Operators
| I/O Functions
| I/O Enums

## Classes
class | CGAL::IO::Color
| An object of the class `Color` is a color available for drawing operations in many CGAL output streams. More...
class | CGAL::IO::Basic_color_streambuf< CharT, Traits >
| The class template `Basic_color_streambuf` wraps another `basic_streambuf` and automatically adds ANSI color codes to the output. More...
class | CGAL::IO::Basic_color_stream_guard< StreamT >
| RAII helper class for temporarily installing a color streambuf on a stream. More...
class | CGAL::IO::Basic_indenting_streambuf< CharT, Traits >
| The class template `Basic_indenting_streambuf` wraps another `basic_streambuf` and automatically adds indentation at the beginning of each line. More...
class | CGAL::IO::Basic_indenting_stream_guard< StreamT >
| RAII helper class for temporarily installing an indenting streambuf on a stream. More...
class | CGAL::Istream_iterator< T, Stream >
| The class `Istream_iterator` is an input iterator adaptor for the input stream class `Stream` and value type `T`. More...
class | CGAL::Ostream_iterator< T, Stream >
| The class `Ostream_iterator` is an output iterator adaptor for the output stream class `Stream` and value type `T`. More...
class | CGAL::Verbose_ostream
| The class `Verbose_ostream` can be used as an output stream. More...
class | CGAL::Output_rep< T, F >
| The purpose of `Output_rep` is to provide a way to control output formatting that works independently of the object's stream output operator. More...
class | CGAL::Input_rep< T >
| The definition of `Input_rep` is completely symmetric to `Output_rep`. More...

## Typedefs
using | CGAL::IO::Color_streambuf = Basic_color_streambuf< char >
| Type alias for `Basic_color_streambuf<char>`
using | CGAL::IO::Color_wstreambuf = Basic_color_streambuf< wchar_t >
| Type alias for `Basic_color_streambuf<wchar_t>`
using | CGAL::IO::Color_stream_guard = Basic_color_stream_guard< std::ostream >
| Type alias for `Basic_color_stream_guard<std::ostream>`
using | CGAL::IO::Color_wstream_guard = Basic_color_stream_guard< std::wostream >
| Type alias for `Basic_color_stream_guard<std::wostream>`
using | CGAL::IO::Indenting_streambuf = Basic_indenting_streambuf< char >
| Type alias for `Basic_indenting_streambuf<char>`
using | CGAL::IO::Indenting_wstreambuf = Basic_indenting_streambuf< wchar_t >
| Type alias for `Basic_indenting_streambuf<wchar_t>`
using | CGAL::IO::Indenting_stream_guard = Basic_indenting_stream_guard< std::ostream >
| Type alias for `basic_indenting_stream_guard<std::ostream>`
using | CGAL::IO::Indenting_wstream_guard = Basic_indenting_stream_guard< std::wostream >
| Type alias for `basic_indenting_stream_guard<std::wostream>`

## Functions
template<Ansi_color... colors, typename... Streams>
auto | CGAL::IO::make_color_guards (Streams &... streams)
| creates color guards for multiple streams simultaneously.
template<typename CharT , typename Traits >
bool | CGAL::IO::stream_supports_color (const std::basic_ostream< CharT, Traits > &stream)
| checks if a stream is attached to a terminal that supports colors.
template<typename... Streams>
auto | CGAL::IO::make_indenting_guards (int spaces_per_level, Streams &... streams)
| creates indenting guards for multiple streams simultaneously.
template<typename... Streams>
auto | CGAL::IO::make_indenting_guards (const std::string &indent_string, Streams &... streams)
| creates indenting guards for multiple streams with a custom indent string.
template<class T >
Output_rep< T > | CGAL::IO::oformat (const T &t)
| Convenience function to construct an output representation (`Output_rep`) for type `T`.
template<class T , class F >
Output_rep< T, F > | CGAL::IO::oformat (const T &t, F format)
| Convenience function to construct an output representation (`Output_rep`) for type `T`.
template<class T >
Input_rep< T > | CGAL::IO::iformat (T &t)
| The definition of this function is completely symmetric to `oformat()`.
Mode | CGAL::IO::get_mode (std::ios &s)
| returns the printing mode of the IO stream `s`.
Mode | CGAL::IO::set_ascii_mode (std::ios &s)
| sets the mode of the IO stream `s` to be the `ASCII` mode.
Mode | CGAL::IO::set_binary_mode (std::ios &s)
| sets the mode of the IO stream `s` to be the `BINARY` mode.
Mode | CGAL::IO::set_pretty_mode (std::ios &s)
| sets the mode of the IO stream `s` to be the `PRETTY` mode.
Mode | CGAL::IO::set_mode (std::ios &s, Mode m)
| sets the printing mode of the IO stream `s`.
bool | CGAL::IO::is_pretty (std::ios &s)
| checks if the IO stream `s` is in `PRETTY` mode.
bool | CGAL::IO::is_ascii (std::ios &s)
| checks if the IO stream `s` is in `ASCII` mode.
bool | CGAL::IO::is_binary (std::ios &s)
| checks if the IO stream `s` is in `BINARY` mode.

## Function Documentation

## ◆ get_mode()

Mode CGAL::IO::get_mode | ( | std::ios & | s | ) |

`#include <CGAL/IO/io.h>`

returns the printing mode of the IO stream `s`.

`CGAL::IO::Mode`

See also
  `CGAL::IO::set_mode()`
  `CGAL::IO::set_ascii_mode()`
  `CGAL::IO::set_binary_mode()`
  `CGAL::IO::set_pretty_mode()`
  `CGAL::IO::is_ascii()`
  `CGAL::IO::is_binary()`
  `CGAL::IO::is_pretty()`

## ◆ is_ascii()

bool CGAL::IO::is_ascii | ( | std::ios & | s | ) |

`#include <CGAL/IO/io.h>`

checks if the IO stream `s` is in `ASCII` mode.

`CGAL::IO::Mode`

See also
  `CGAL::IO::set_mode()`
  `CGAL::IO::set_ascii_mode()`
  `CGAL::IO::set_binary_mode()`
  `CGAL::IO::set_pretty_mode()`
  `CGAL::IO::get_mode()`
  `CGAL::IO::is_binary()`
  `CGAL::IO::is_pretty()`

## ◆ is_binary()

bool CGAL::IO::is_binary | ( | std::ios & | s | ) |

`#include <CGAL/IO/io.h>`

checks if the IO stream `s` is in `BINARY` mode.

`CGAL::IO::Mode`

See also
  `CGAL::IO::set_mode()`
  `CGAL::IO::set_ascii_mode()`
  `CGAL::IO::set_binary_mode()`
  `CGAL::IO::set_pretty_mode()`
  `CGAL::IO::get_mode()`
  `CGAL::IO::is_ascii()`
  `CGAL::IO::is_pretty()`

## ◆ is_pretty()

bool CGAL::IO::is_pretty | ( | std::ios & | s | ) |

`#include <CGAL/IO/io.h>`

checks if the IO stream `s` is in `PRETTY` mode.

`CGAL::IO::Mode`

See also
  `CGAL::IO::set_mode()`
  `CGAL::IO::set_ascii_mode()`
  `CGAL::IO::set_binary_mode()`
  `CGAL::IO::set_pretty_mode()`
  `CGAL::IO::get_mode()`
  `CGAL::IO::is_ascii()`
  `CGAL::IO::is_binary()`

## ◆ make_color_guards()

template<Ansi_color... colors, typename... Streams>

auto CGAL::IO::make_color_guards | ( | Streams &... | streams | ) |

`#include <CGAL/IO/Color_ostream.h>`

creates color guards for multiple streams simultaneously.

This helper function creates `Basic_color_stream_guard` objects for multiple streams at once. All streams will use the same color settings, and their original streambufs will be automatically restored when the guards go out of scope. The guards are returned in a tuple.

Template Parameters

  colors | Non-type template parameters specifying the colors to combine
  Streams | The stream types (deduced from arguments)

Parameters

  streams | The streams to apply colors to

Returns
  A tuple of `Basic_color_stream_guard` objects

See also
  Basic_color_stream_guard

Example usage:

auto guards =
CGAL::IO::make_color_guards<CGAL::IO::Ansi_color::Bold, CGAL::IO::Ansi_color::Green>(std::cout, std::clog);

## ◆ make_indenting_guards() [1/2]

template<typename... Streams>

auto CGAL::IO::make_indenting_guards | ( | const std::string & | indent_string,
|  | Streams &... | streams
| ) |  |

`#include <CGAL/IO/Indenting_ostream.h>`

creates indenting guards for multiple streams with a custom indent string.

This overload allows specifying a custom indentation string instead of a number of spaces.

Template Parameters

  Streams | The stream types (deduced from arguments)

Parameters

  indent_string | The indentation string to use
  streams | The streams to apply indentation to

Returns
  A tuple of Basic_indenting_stream_guard objects

See also
  Basic_indenting_stream_guard

## ◆ make_indenting_guards() [2/2]

template<typename... Streams>

auto CGAL::IO::make_indenting_guards | ( | int | spaces_per_level,
|  | Streams &... | streams
| ) |  |

`#include <CGAL/IO/Indenting_ostream.h>`

creates indenting guards for multiple streams simultaneously.

This helper function creates `Basic_indenting_stream_guard` objects for multiple streams at once. All streams will use the same indentation settings, and their original streambufs will be automatically restored when the guards go out of scope. The guards are returned in a tuple.

Template Parameters

  Streams | The stream types (deduced from arguments)

Parameters

  spaces_per_level | Number of spaces per indentation level
  streams | The streams to apply indentation to

Returns
  A tuple of Basic_indenting_stream_guard objects

See also
  Basic_indenting_stream_guard

Example usage:

auto guards = CGAL::IO::make_indenting_guards(2, std::cout, std::cerr);
std::cout << "Indented output\n";
std::cerr << "Indented error\n";

Examples
  Stream_support/indenting_ostream.cpp.

## ◆ oformat() [1/2]

template<class T >

Output_rep< T > CGAL::IO::oformat | ( | const T & | t | ) |

`#include <CGAL/IO/io.h>`

Convenience function to construct an output representation (`Output_rep`) for type `T`.

Generic IO for type `T`.

## ◆ oformat() [2/2]

template<class T , class F >

Output_rep< T, F > CGAL::IO::oformat | ( | const T & | t,
|  | F | format
| ) |  |

`#include <CGAL/IO/io.h>`

Convenience function to construct an output representation (`Output_rep`) for type `T`.

Generic IO for type `T` with formatting tag.

## ◆ set_ascii_mode()

Mode CGAL::IO::set_ascii_mode | ( | std::ios & | s | ) |

`#include <CGAL/IO/io.h>`

sets the mode of the IO stream `s` to be the `ASCII` mode.

Returns the previous mode of `s`.

`CGAL::IO::Mode`

See also
  `CGAL::IO::set_mode()`
  `CGAL::IO::set_binary_mode()`
  `CGAL::IO::set_pretty_mode()`
  `CGAL::IO::get_mode()`
  `CGAL::IO::is_ascii()`
  `CGAL::IO::is_binary()`
  `CGAL::IO::is_pretty()`

## ◆ set_binary_mode()

Mode CGAL::IO::set_binary_mode | ( | std::ios & | s | ) |

`#include <CGAL/IO/io.h>`

sets the mode of the IO stream `s` to be the `BINARY` mode.

Returns the previous mode of `s`.

`CGAL::IO::Mode`

See also
  `CGAL::IO::set_mode()`
  `CGAL::IO::set_ascii_mode()`
  `CGAL::IO::set_pretty_mode()`
  `CGAL::IO::get_mode()`
  `CGAL::IO::is_ascii()`
  `CGAL::IO::is_binary()`
  `CGAL::IO::is_pretty()`

## ◆ set_mode()

Mode CGAL::IO::set_mode | ( | std::ios & | s,
|  | Mode | m
| ) |  |

`#include <CGAL/IO/io.h>`

sets the printing mode of the IO stream `s`.

`CGAL::IO::Mode`

See also
  `CGAL::IO::set_ascii_mode()`
  `CGAL::IO::set_binary_mode()`
  `CGAL::IO::set_pretty_mode()`
  `CGAL::IO::get_mode()`
  `CGAL::IO::is_ascii()`
  `CGAL::IO::is_binary()`
  `CGAL::IO::is_pretty()`

## ◆ set_pretty_mode()

Mode CGAL::IO::set_pretty_mode | ( | std::ios & | s | ) |

`#include <CGAL/IO/io.h>`

sets the mode of the IO stream `s` to be the `PRETTY` mode.

Returns the previous mode of `s`.

`CGAL::IO::Mode`

See also
  `CGAL::IO::set_mode()`
  `CGAL::IO::set_ascii_mode()`
  `CGAL::IO::set_binary_mode()`
  `CGAL::IO::get_mode()`
  `CGAL::IO::is_ascii()`
  `CGAL::IO::is_binary()`
  `CGAL::IO::is_pretty()`

## ◆ stream_supports_color()

template<typename CharT , typename Traits >

bool CGAL::IO::stream_supports_color | ( | const std::basic_ostream< CharT, Traits > & | stream | ) |

`#include <CGAL/IO/Color_ostream.h>`

checks if a stream is attached to a terminal that supports colors.

This function checks if the given output stream is connected to a terminal (TTY) that can display ANSI color codes. It performs the following checks:

1. Verifies the stream is attached to a TTY device using `isatty()`
2. Checks if the `TERM` environment variable indicates color support
3. Respects the `NO_COLOR` environment variable (if set, colors are disabled)
4. Respects the `CLICOLOR_FORCE` environment variable (if set, colors are enabled)

Parameters

  stream | The output stream to check (e.g., `std::cout`, `std::cerr`)

Returns
  `true` if the stream supports color output, `false` otherwise

Note
  This function may return false negatives on some systems, but should never return false positives (it won't report color support where it doesn't exist).

See also
  Basic_color_streambuf

Example usage:

if(CGAL::IO::stream_supports_color(std::cout)) {
CGAL::IO::Color_stream_guard guard(std::cout, CGAL::IO::Ansi_color::Red);
std::cout << "This text is red!\n";
} else {
std::cout << "Plain text output\n";
}

Examples
  Stream_support/color_ostream.cpp.