Some utility routines for GeographicLib. More...

#include <GeographicLib/Utility.hpp>

Static Public Member Functions
static int	day (int y, int m=1, int d=1)

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

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

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

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

static int	dow (int s)

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

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

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

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

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

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

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

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

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)

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 bool	ParseLine (const std::string &line, std::string &key, std::string &value, char equals='\0', char comment='#')

static int	set_digits (int ndigits=0)

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

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

◆ day() [1/2]

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

static

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 22 of file Utility.cpp.

Referenced by day().

◆ day() [2/2]

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

static

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 74 of file Utility.cpp.

References date(), day(), and str().

◆ date() [1/2]

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

static

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 89 of file Utility.cpp.

Referenced by day().

◆ date() [2/2]

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

static

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 110 of file Utility.cpp.

◆ dow() [1/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 108 of file Utility.hpp.

References dow().

Referenced by dow().

◆ dow() [2/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 117 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. The string "now" is interpreted as the present date.

Definition at line 135 of file Utility.hpp.

◆ str()

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, except that boolalpha is used to represent bools as "true" and "false". There is an overload of this function if T is Math::real; this deals with inf and nan.

Definition at line 161 of file Utility.hpp.

Referenced by GeographicLib::MGRS::Check(), day(), GeographicLib::DMS::DecodeLatLon(), GeographicLib::UTMUPS::DecodeZone(), GeographicLib::DMS::Encode(), GeographicLib::UTMUPS::EncodeZone(), GeographicLib::MGRS::Forward(), GeographicLib::UTMUPS::Forward(), GeographicLib::Geohash::Forward(), GeographicLib::GARS::Forward(), GeographicLib::Georef::Forward(), GeographicLib::GeoCoords::GeoRepresentation(), GeographicLib::OSGB::GridReference(), GeographicLib::SphericalEngine::coeff::readcoeffs(), GeographicLib::Georef::Reverse(), GeographicLib::MGRS::Reverse(), GeographicLib::UTMUPS::Reverse(), and GeographicLib::UTMUPS::StandardZone().

◆ trim()

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

static

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 149 of file Utility.cpp.

Referenced by ParseLine(), and val().

◆ lookup() [1/2]

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

static

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 160 of file Utility.cpp.

Referenced by GeographicLib::DMS::Decode(), GeographicLib::OSGB::GridReference(), GeographicLib::GARS::Reverse(), GeographicLib::Geohash::Reverse(), GeographicLib::Georef::Reverse(), and GeographicLib::MGRS::Reverse().

◆ lookup() [2/2]

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

static

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 165 of file Utility.cpp.

◆ 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 225 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 260 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". (Recent versions of the msys shell appear not to have this problem.)

Definition at line 298 of file Utility.hpp.

◆ 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 321 of file Utility.hpp.

References GeographicLib::Math::bigendian.

◆ 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 372 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 390 of file Utility.hpp.

References GeographicLib::Math::bigendian.

◆ 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 437 of file Utility.hpp.

◆ ParseLine()

bool GeographicLib::Utility::ParseLine	(	const std::string &	line,
		std::string &	key,
		std::string &	value,
		char	equals = `'\0'`,
		char	comment = `'#'`
	)

static

Parse a KEY [=] VALUE line.

Parameters

[in]	line	the input line.
[out]	key	the KEY.
[out]	value	the VALUE.
[in]	equals	character representing "equals" to separate KEY and VALUE, if NULL (the default) use first space character.
[in]	comment	character to use as the comment character; if non-NULL, this character and everything after it is discarded; default is '#'.

Exceptions

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

Returns: whether a key was found.

The comment character (default is '#') and everything after it are discarded and the result trimmed of leading and trailing white space. Use the equals delimiter character (or, if it is NULL – the default, the first white space) to separate key and value. key and value are trimmed of leading and trailing white space. If key is empty, then value is set to "" and false is returned.

Definition at line 170 of file Utility.cpp.

References trim().

◆ 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).

Note: Use Math::digits() to return the current precision in bits.

Definition at line 184 of file Utility.cpp.

References GeographicLib::Math::set_digits().

◆ val() [2/2]

template<>

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

inlinestatic

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

Parameters

[in] s the string to be converted.

Exceptions

GeographicErr is s is not readable as a T.

Returns: boolean value.

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.

Definition at line 515 of file Utility.hpp.

References trim().

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

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ day() [1/2]

◆ day() [2/2]

◆ date() [1/2]

◆ date() [2/2]

◆ dow() [1/2]

◆ dow() [2/2]

◆ fractionalyear()

◆ str()

◆ trim()

◆ lookup() [1/2]

◆ lookup() [2/2]

◆ val() [1/2]

◆ nummatch()

◆ fract()

◆ readarray() [1/2]

◆ readarray() [2/2]

◆ writearray() [1/2]

◆ writearray() [2/2]

◆ ParseLine()

◆ set_digits()

◆ val() [2/2]