PointWriter module

Module contents

class PointWriter

Write points of any type as delimited text

This class writes a sequence of points to a file in delimited text format. You can control the destination, the delimiter, the record separator (usually newline) and whether or not a header line is written.

The header line contains information about the point’s dimension, coordinate system, object ID and timestamp (for trajectory points) and custom properties (if any).

Public Functions

inline PointWriter()

Instantiate PointWriter using a default configuration

Set the default configuration values of the writer

Defaults:

coordinate_precision = 8
field_delimiter = “,”
null_value = “”
quote_character = “””

* record_delimiter = “\n”

* timestamp_format = “Y-m-d H:M:S”
write_header = true

inline PointWriter(PointWriter const &other)

Copy contructor, PointWriter with a copy of another

Parameters:: other – [in] PointWriter to copy from

inline PointWriter(std::ostream &_output)

Instantiate a PointWriter using a std::ostream and default configuration

Set the default configuration values of the writer

Defaults:

coordinate_precision = 8
field_delimiter = “,”
null_value = “”
quote_character = “””

* record_delimiter = “\n”

* timestamp_format = “Y-m-d H:M:S”
write_header = true

Parameters:: ostream – [in] Output to write points to

inline PointWriter &operator=(PointWriter const &other)

Assign a PointWriter to the value of another.

Parameters:: other – [in] PointWriter to assign value of
Returns:: PointWriter with the new assigned value

inline bool operator==(PointWriter const &other) const

Check whether one PointWriter is equal to another by comparing the properties.

Two items are equal if all of their properties are equal.

Parameters:: other – [in] PointWriter for comparison
Returns:: Boolean indicating equivalency

inline bool operator!=(PointWriter const &other) const

Check whether two PointWriter are unequal.

Parameters:: other – [in] PointWriter for comparison
Returns:: Boolean indicating equivalency

inline void set_output(std::ostream &out)

Set the stream where points will be written

This can be any std::ostream.

Note

You are resposible for ensuring that the stream does not go out of scope until you are done writing points.

Parameters:: out – [in] Stream where points will be written

inline std::ostream &output() const

Return the stream where points will be written

Returns:: output stream

inline void set_field_delimiter(string_type const &delim)

Set the field delimiter

This string will be inserted between each field as points are written.

Parameters:: delim – [in] Delimiter string

inline string_type field_delimiter() const

Return the field delimiter

Returns:: Field delimiter

inline void set_record_delimiter(string_type const &sep)

Set the record separator (end-of-line string)

This string will be written after each point. By default it’s std::endl (the newline string).

Parameters:: sep – [in] String separator

inline void set_timestamp_format(string_type const &format)

Set format for writing timestamps

There are as many ways to write timestamps as there are programs to write them. We have our default (YYYY-MM-DD HH:MM:SS) but sometimes you will need to specify some other format for interoperability.

This method sets a format string for timestamps using the flags in boost::date_time::time_facet.

Parameters:: format – [in] Format string for timestamps

inline string_type timestamp_format() const

Retrieve the timestamp format

Returns:: The time timestamp format

inline string_type record_delimiter() const

Retrieve the record separator (end-of-line string)

Returns:: Return the record separator (end-of-line string)

inline void set_quote_character(string_type const &quotes)

Set the quote character

This character may be used to enclose a field containing lots of characters that would otherwise need to be escaped. We have to know what it is so that we can escape it ourselves when we encounter the quote character inside fields.

Parameters:: quotes – [in] Zero or one character to be used as quotation marks

inline string_type quote_character() const

Return the current quote characters

Returns:: Current quote character

inline void set_write_header(bool onoff)

Set whether or not to write a header

The header string describes the contents of a point: coordinate system, properties (if any), number of coordinates. By default it will be written at the beginning of a sequence of points. You can turn it off with this function.

Parameters:: onoff – [in] Boolean flag

inline bool write_header() const

Return whether or not the header will be written

Returns:: The flag indicating to write the header or not

template<typename point_iter_type> inline int write(point_iter_type point_begin, point_iter_type point_end)

Write out the points

The difference between write() and write_point_header_tokens() is that write() inserts a record seperator after the header and after each point

Parameters:

point_begin – [in] Point to start writing from
point_end – [in] Last point to write out

Returns:

The number of points written

inline void set_coordinate_precision(std::size_t num_digits)

Set the decimal precision for writing coordinates

Internally, Tracktable stores coordinates as double-precision floating numbers. It is highly unlikely that trajectory data needs absolutely all of that precision. Since it takes up lots of space when we write data to disk, it is useful to be able to ask for reduced (or increased) precision.

Parameters:: num_digits – [in] Number of digits of precision

inline std::size_t coordinate_precision() const

Retreive the coordinate decimal precision

Returns:: The decimal precision

inline void set_null_value(string_type const &_null_value)

Set the string representation for nulls

Property values that were never set are considered to hold a null value. This method lets you set how nulls will be written to disk. The default value is the empty string “”.

Parameters:: _null_value – [in] Desired string representation of nulls

inline string_type null_value() const

Retreive the null value

Returns:: The representation of the null value

Private Functions

inline void set_default_configuration()

Set the default configuration values of the writer

Defaults:

coordinate_precision = 8
field_delimiter = “,”
null_value = “”
quote_character = “””

* record_delimiter = “\n”

* timestamp_format = “Y-m-d H:M:S”
write_header = true

template<typename point_type, typename out_iter_type> inline void write_point_header_tokens(point_type const &example_point, out_iter_type _output)

Write tokens out the header

Header structure:

Header token (currently P)
Domain
Dimension
HasObjectId
HasTimestamp
Number of properties 7, 8: name, type of custom property #1 9, 10: name, type of custom property #2 (etc)

Parameters:

example_point – [in] Point to generate an example output from
_output – [in] Where to write the tokens to

template<typename point_iter_type, typename out_iter_type> inline int write_many_points_to_tokens(point_iter_type point_begin, point_iter_type point_end, out_iter_type _output)

Write out multiple point tokens

Parameters:

point_begin – [in] Point to start writing from
point_end – [in] Last point to write out
_output – [in] Where to write the tokens to

template<typename point_type, typename out_iter_type> inline void write_point_tokens(point_type const &point, out_iter_type _output, std::size_t num_properties_expected)

Write out point tokens

Parameters:

point – [in] Point to write out
_output – [in] Where to write the tokens to
num_properties_expected – [in] The number of properties the point has

template<typename token_iter_type> inline void write_tokens_to_stream(token_iter_type begin, token_iter_type end)

Private Members

std::size_t CoordinatePrecision

PropertyConverter PropertyWriter

string_type TimestampFormat

TokenWriter TokenSink

bool WriteHeader

Friends

friend class TrajectoryWriter