Some utility routines for GeographicLib. More...

#include <Utility.hpp>

Static Public Member Functions
static void	date (const std::string &s, int &y, int &m, int &d)

static void	date (int s, int &y, int &m, int &d)

static int	day (int y, int m, int d, bool check)

static int	day (int y, int m=1, int d=1)

static int	dow (int s)

static int	dow (int y, int m, int d)

template<typename T >
static T	fract (const std::string &s)

template<typename T >
static T	fractionalyear (const std::string &s)

static int	lookup (const char *s, char c)

static int	lookup (const std::string &s, char c)

template<typename T >
static T	num (const std::string &s)

template<typename T >
static T	nummatch (const std::string &s)

static bool	ParseLine (const std::string &line, std::string &key, std::string &val)

template<typename ExtT , typename IntT , bool bigendp>
static void	readarray (std::istream &str, IntT array[], size_t num)

template<typename ExtT , typename IntT , bool bigendp>
static void	readarray (std::istream &str, std::vector< IntT > &array)

static int	set_digits (int ndigits=0)

static std::string	str (Math::real x, int p=-1)

template<typename T >
static std::string	str (T x, int p=-1)

static std::string	trim (const std::string &s)

template<typename T >
static T	val (const std::string &s)

template<>
bool	val (const std::string &s)

template<typename ExtT , typename IntT , bool bigendp>
static void	writearray (std::ostream &str, const IntT array[], size_t num)

template<typename ExtT , typename IntT , bool bigendp>
static void	writearray (std::ostream &str, std::vector< IntT > &array)

Static Private Member Functions
static bool	gregorian (int s)

static bool	gregorian (int y, int m, int d)

Detailed Description

Some utility routines for GeographicLib.

Example of use:

// Example of using the GeographicLib::Utility class
 
#include <iostream>
#include <exception>
#include <GeographicLib/Utility.hpp>
 
using namespace std;
using namespace GeographicLib;
 
int main() {
  try {
    int
      d1 = Utility::day(1939, 9, 3),  // Britain declares war on Germany
      d2 = Utility::day(1945, 8, 15); // Japan surrenders
    cout << d2 - d1 << "\n";          // Length of Second World War for Britain
  }
  catch (const exception& e) {
    cerr << "Caught exception: " << e.what() << "\n";
    return 1;
  }
}

Definition at line 35 of file Utility.hpp.

Member Function Documentation

◆ date() [1/2]

static void GeographicLib::Utility::date	(	const std::string &	s,
		int &	y,
		int &	m,
		int &	d
	)

inlinestatic

Given a date as a string in the format yyyy, yyyy-mm, or yyyy-mm-dd, return the numeric values for the year, month, and day. No checking is done on these values. The string "now" is interpreted as the present date (in UTC).

Parameters

[in]	s	the date in string format.
[out]	y	the year.
[out]	m	the month, Jan = 1, etc.
[out]	d	the day of the month.

Exceptions

GeographicErr is s is malformed.

Definition at line 179 of file Utility.hpp.

◆ date() [2/2]

static void GeographicLib::Utility::date	(	int	s,
		int &	y,
		int &	m,
		int &	d
	)

inlinestatic

Given a day (counting from 0001-01-01 as day 1), return the date.

Parameters

[in]	s	the sequential day number (must be positive)
[out]	y	the year.
[out]	m	the month, Jan = 1, etc.
[out]	d	the day of the month.

Definition at line 146 of file Utility.hpp.

◆ day() [1/2]

static int GeographicLib::Utility::day	(	int	y,
		int	m,
		int	d,
		bool	check
	)

inlinestatic

Convert a date to the day numbering sequentially starting with 0001-01-01 as day 1.

Parameters

[in]	y	the year (must be positive).
[in]	m	the month, Jan = 1, etc. (must be positive). Default = 1.
[in]	d	the day of the month (must be positive). Default = 1.
[in]	check	whether to check the date.

Exceptions

GeographicErr if the date is invalid and check is true.

Returns: the sequential day number.

Definition at line 123 of file Utility.hpp.

◆ day() [2/2]

static int GeographicLib::Utility::day	(	int	y,
		int	m = `1`,
		int	d = `1`
	)

inlinestatic

Convert a date to the day numbering sequentially starting with 0001-01-01 as day 1.

Parameters

[in]	y	the year (must be positive).
[in]	m	the month, Jan = 1, etc. (must be positive). Default = 1.
[in]	d	the day of the month (must be positive). Default = 1.

Returns: the sequential day number.

Definition at line 60 of file Utility.hpp.

◆ dow() [1/2]

static int GeographicLib::Utility::dow ( int s )

inlinestatic

Given the sequential day, return the day of the week.

Parameters

[in] s the sequential day (must be positive).

Returns: the day of the week with Sunday, Monday–Saturday = 0, 1–6.

Definition at line 236 of file Utility.hpp.

◆ dow() [2/2]

static int GeographicLib::Utility::dow	(	int	y,
		int	m,
		int	d
	)

inlinestatic

Given the date, return the day of the week.

Parameters

[in]	y	the year (must be positive).
[in]	m	the month, Jan = 1, etc. (must be positive).
[in]	d	the day of the month (must be positive).

Returns: the day of the week with Sunday, Monday–Saturday = 0, 1–6.

Definition at line 227 of file Utility.hpp.

◆ fract()

template<typename T >

static T GeographicLib::Utility::fract ( const std::string & s )

inlinestatic

Read a simple fraction, e.g., 3/4, from a string to an object of type T.

Template Parameters

T	the type of the return value.

Parameters

[in] s the string to be converted.

Exceptions

GeographicErr is s is not readable as a fraction of type T.

Returns: object of type T

Note: The msys shell under Windows converts arguments which look like pathnames into their Windows equivalents. As a result the argument "-1/300" gets mangled into something unrecognizable. A workaround is to use a floating point number in the numerator, i.e., "-1.0/300".

Definition at line 439 of file Utility.hpp.

◆ fractionalyear()

template<typename T >

static T GeographicLib::Utility::fractionalyear ( const std::string & s )

inlinestatic

Convert a string representing a date to a fractional year.

Template Parameters

T	the type of the argument.

Parameters

[in] s the string to be converted.

Exceptions

GeographicErr if s can't be interpreted as a date.

Returns: the fractional year.

The string is first read as an ordinary number (e.g., 2010 or 2012.5); if this is successful, the value is returned. Otherwise the string should be of the form yyyy-mm or yyyy-mm-dd and this is converted to a number with 2010-01-01 giving 2010.0 and 2012-07-03 giving 2012.5.

Definition at line 253 of file Utility.hpp.

◆ gregorian() [1/2]

static bool GeographicLib::Utility::gregorian ( int s )

inlinestaticprivate

Definition at line 46 of file Utility.hpp.

◆ gregorian() [2/2]

static bool GeographicLib::Utility::gregorian	(	int	y,
		int	m,
		int	d
	)

inlinestaticprivate

Definition at line 37 of file Utility.hpp.

◆ lookup() [1/2]

static int GeographicLib::Utility::lookup	(	const char *	s,
		char	c
	)

inlinestatic

Lookup up a character in a char*.

Parameters

[in]	s	the char* string to be searched.
[in]	c	the character to look for.

Returns: the index of the first occurrence character in the string or −1 is the character is not present.

c is converted to upper case before search s. Therefore, it is intended that s should not contain any lower case letters.

Definition at line 475 of file Utility.hpp.

◆ lookup() [2/2]

static int GeographicLib::Utility::lookup	(	const std::string &	s,
		char	c
	)

inlinestatic

Lookup up a character in a string.

Parameters

[in]	s	the string to be searched.
[in]	c	the character to look for.

Returns: the index of the first occurrence character in the string or −1 is the character is not present.

c is converted to upper case before search s. Therefore, it is intended that s should not contain any lower case letters.

Definition at line 459 of file Utility.hpp.

◆ num()

template<typename T >

static T GeographicLib::Utility::num ( const std::string & s )

inlinestatic

Deprecated:: An old name for val<T>(s).

Definition at line 387 of file Utility.hpp.

◆ nummatch()

template<typename T >

static T GeographicLib::Utility::nummatch ( const std::string & s )

inlinestatic

Match "nan" and "inf" (and variants thereof) in a string.

Template Parameters

T	the type of the return value (this should be a floating point type).

Parameters

[in] s the string to be matched.

Returns: appropriate special value (±∞, nan) or 0 if none is found.

White space is not allowed at the beginning or end of s.

Definition at line 402 of file Utility.hpp.

◆ ParseLine()

bool GeographicLib::Utility::ParseLine	(	const std::string &	line,
		std::string &	key,
		std::string &	val
	)

static

Parse a KEY VALUE line.

Parameters

[in]	line	the input line.
[out]	key	the key.
[out]	val	the value.

Exceptions

std::bad_alloc if memory for the internal strings can't be allocated.

Returns: whether a key was found.

A # character and everything after it are discarded. If the result is just white space, the routine returns false (and key and val are not set). Otherwise the first token is taken to be the key and the rest of the line (trimmed of leading and trailing white space) is the value.

Definition at line 22 of file Utility.cpp.

◆ readarray() [1/2]

template<typename ExtT , typename IntT , bool bigendp>

static void GeographicLib::Utility::readarray	(	std::istream &	str,
		IntT	array[],
		size_t	num
	)

inlinestatic

Read data of type ExtT from a binary stream to an array of type IntT. The data in the file is in (bigendp ? big : little)-endian format.

Template Parameters

ExtT	the type of the objects in the binary stream (external).
IntT	the type of the objects in the array (internal).
bigendp	true if the external storage format is big-endian.

Parameters

[in]	str	the input stream containing the data of type ExtT (external).
[out]	array	the output array of type IntT (internal).
[in]	num	the size of the array.

Exceptions

GeographicErr if the data cannot be read.

Definition at line 494 of file Utility.hpp.

◆ readarray() [2/2]

template<typename ExtT , typename IntT , bool bigendp>

static void GeographicLib::Utility::readarray	(	std::istream &	str,
		std::vector< IntT > &	array
	)

inlinestatic

Read data of type ExtT from a binary stream to a vector array of type IntT. The data in the file is in (bigendp ? big : little)-endian format.

Template Parameters

ExtT	the type of the objects in the binary stream (external).
IntT	the type of the objects in the array (internal).
bigendp	true if the external storage format is big-endian.

Parameters

[in]	str	the input stream containing the data of type ExtT (external).
[out]	array	the output vector of type IntT (internal).

Exceptions

GeographicErr if the data cannot be read.

Definition at line 545 of file Utility.hpp.

◆ set_digits()

int GeographicLib::Utility::set_digits ( int ndigits = 0 )

static

Set the binary precision of a real number.

Parameters

[in] ndigits the number of bits of precision. If ndigits is 0 (the default), then determine the precision from the environment variable GEOGRAPHICLIB_DIGITS. If this is undefined, use ndigits = 256 (i.e., about 77 decimal digits).

Returns: the resulting number of bits of precision.

This only has an effect when GEOGRAPHICLIB_PRECISION = 5. The precision should only be set once and before calls to any other GeographicLib functions. (Several functions, for example Math::pi(), cache the return value in a static local variable. The precision needs to be set before a call to any such functions.) In multi-threaded applications, it is necessary also to set the precision in each thread (see the example GeoidToGTX.cpp).

Definition at line 48 of file Utility.cpp.

◆ str() [1/2]

static std::string GeographicLib::Utility::str	(	Math::real	x,
		int	p = `-1`
	)

inlinestatic

Convert a Math::real object to a string.

Parameters

[in]	x	the value to be converted.
[in]	p	the precision used (default −1).

Exceptions

std::bad_alloc if memory for the string can't be allocated.

Returns: the string representation.

If p ≥ 0, then the number fixed format is used with p bits of precision. With p < 0, there is no manipulation of the format. This is an overload of str<T> which deals with inf and nan.

Definition at line 294 of file Utility.hpp.

◆ str() [2/2]

template<typename T >

static std::string GeographicLib::Utility::str	(	T	x,
		int	p = `-1`
	)

inlinestatic

Convert a object of type T to a string.

Template Parameters

T	the type of the argument.

Parameters

[in]	x	the value to be converted.
[in]	p	the precision used (default −1).

Exceptions

std::bad_alloc if memory for the string can't be allocated.

Returns: the string representation.

If p ≥ 0, then the number fixed format is used with p bits of precision. With p < 0, there is no manipulation of the format.

Definition at line 276 of file Utility.hpp.

◆ trim()

static std::string GeographicLib::Utility::trim ( const std::string & s )

inlinestatic

Trim the white space from the beginning and end of a string.

Parameters

[in] s the string to be trimmed

Returns: the trimmed string

Definition at line 324 of file Utility.hpp.

◆ val() [1/2]

template<typename T >

static T GeographicLib::Utility::val ( const std::string & s )

inlinestatic

Convert a string to type T.

Template Parameters

T	the type of the return value.

Parameters

[in] s the string to be converted.

Exceptions

GeographicErr is s is not readable as a T.

Returns: object of type T.

White space at the beginning and end of s is ignored.

Special handling is provided for some types.

If T is a floating point type, then inf and nan are recognized.

If T is bool, then s should either be string a representing 0 (false) or 1 (true) or one of the strings

"false", "f", "nil", "no", "n", "off", or "" meaning false,
"true", "t", "yes", "y", or "on" meaning true;

case is ignored.

If T is std::string, then s is returned (with the white space at the beginning and end removed).

Definition at line 359 of file Utility.hpp.

◆ val() [2/2]

template<>

bool GeographicLib::Utility::val ( const std::string & s )

inlinestatic

The specialization of Utility::val<T>() for bools.

Definition at line 663 of file Utility.hpp.

◆ writearray() [1/2]

template<typename ExtT , typename IntT , bool bigendp>

static void GeographicLib::Utility::writearray	(	std::ostream &	str,
		const IntT	array[],
		size_t	num
	)

inlinestatic

Write data in an array of type IntT as type ExtT to a binary stream. The data in the file is in (bigendp ? big : little)-endian format.

Template Parameters

ExtT	the type of the objects in the binary stream (external).
IntT	the type of the objects in the array (internal).
bigendp	true if the external storage format is big-endian.

Parameters

[out]	str	the output stream for the data of type ExtT (external).
[in]	array	the input array of type IntT (internal).
[in]	num	the size of the array.

Exceptions

GeographicErr if the data cannot be written.

Definition at line 563 of file Utility.hpp.

◆ writearray() [2/2]

template<typename ExtT , typename IntT , bool bigendp>

static void GeographicLib::Utility::writearray	(	std::ostream &	str,
		std::vector< IntT > &	array
	)

inlinestatic

Write data in an array of type IntT as type ExtT to a binary stream. The data in the file is in (bigendp ? big : little)-endian format.

Template Parameters

ExtT	the type of the objects in the binary stream (external).
IntT	the type of the objects in the array (internal).
bigendp	true if the external storage format is big-endian.

Parameters

[out]	str	the output stream for the data of type ExtT (external).
[in]	array	the input vector of type IntT (internal).

Exceptions

GeographicErr if the data cannot be written.

Definition at line 610 of file Utility.hpp.

The documentation for this class was generated from the following files:

Static Public Member Functions

Static Private Member Functions

Detailed Description

Member Function Documentation

◆ date() [1/2]

◆ date() [2/2]

◆ day() [1/2]

◆ day() [2/2]

◆ dow() [1/2]

◆ dow() [2/2]

◆ fract()

◆ fractionalyear()

◆ gregorian() [1/2]

◆ gregorian() [2/2]

◆ lookup() [1/2]

◆ lookup() [2/2]

◆ num()

◆ nummatch()

◆ ParseLine()

◆ readarray() [1/2]

◆ readarray() [2/2]

◆ set_digits()

◆ str() [1/2]

◆ str() [2/2]

◆ trim()

◆ val() [1/2]

◆ val() [2/2]

◆ writearray() [1/2]

◆ writearray() [2/2]