GeographicLib  1.48
Public Member Functions | Static Public Member Functions | List of all members
GeographicLib::Utility Class Reference

Some utility routines for GeographicLib. More...

#include <GeographicLib/Utility.hpp>

Public Member Functions

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

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 str (Math::real x, int p=-1)
 
static std::string trim (const std::string &s)
 
template<typename T >
static T val (const std::string &s)
 
template<typename T >
static T num (const std::string &s)
 
template<typename T >
static T nummatch (const std::string &s)
 
template<typename T >
static T fract (const std::string &s)
 
static int lookup (const std::string &s, char c)
 
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 &val)
 
static int set_digits (int ndigits=0)
 

Detailed Description

Some utility routines for GeographicLib.

Example of use:

// Example of using the GeographicLib::Utility class
#include <iostream>
#include <exception>
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 34 of file Utility.hpp.

Member Function Documentation

◆ day() [1/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]ythe year (must be positive).
[in]mthe month, Jan = 1, etc. (must be positive). Default = 1.
[in]dthe day of the month (must be positive). Default = 1.
Returns
the sequential day number.

Definition at line 59 of file Utility.hpp.

◆ day() [2/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]ythe year (must be positive).
[in]mthe month, Jan = 1, etc. (must be positive). Default = 1.
[in]dthe day of the month (must be positive). Default = 1.
[in]checkwhether to check the date.
Exceptions
GeographicErrif the date is invalid and check is true.
Returns
the sequential day number.

Definition at line 122 of file Utility.hpp.

◆ date() [1/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]sthe sequential day number (must be positive)
[out]ythe year.
[out]mthe month, Jan = 1, etc.
[out]dthe day of the month.

Definition at line 145 of file Utility.hpp.

◆ date() [2/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]sthe date in string format.
[out]ythe year.
[out]mthe month, Jan = 1, etc.
[out]dthe day of the month.
Exceptions
GeographicErris s is malformed.

Definition at line 178 of file Utility.hpp.

◆ 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]ythe year (must be positive).
[in]mthe month, Jan = 1, etc. (must be positive).
[in]dthe day of the month (must be positive).
Returns
the day of the week with Sunday, Monday–Saturday = 0, 1–6.

Definition at line 226 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]sthe sequential day (must be positive).
Returns
the day of the week with Sunday, Monday–Saturday = 0, 1–6.

Definition at line 235 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
Tthe type of the argument.
Parameters
[in]sthe string to be converted.
Exceptions
GeographicErrif 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 252 of file Utility.hpp.

◆ str() [1/2]

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

Convert a object of type T to a string.

Template Parameters
Tthe type of the argument.
Parameters
[in]xthe value to be converted.
[in]pthe precision used (default −1).
Exceptions
std::bad_allocif 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 275 of file Utility.hpp.

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

◆ str() [2/2]

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

Convert a Math::real object to a string.

Parameters
[in]xthe value to be converted.
[in]pthe precision used (default −1).
Exceptions
std::bad_allocif 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 293 of file Utility.hpp.

References GeographicLib::Math::isfinite().

◆ 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]sthe string to be trimmed
Returns
the trimmed string

Definition at line 323 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
Tthe type of the return value.
Parameters
[in]sthe string to be converted.
Exceptions
GeographicErris 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 358 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 386 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
Tthe type of the return value (this should be a floating point type).
Parameters
[in]sthe 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 401 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
Tthe type of the return value.
Parameters
[in]sthe string to be converted.
Exceptions
GeographicErris 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 437 of file Utility.hpp.

◆ lookup()

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

Lookup up a character in a string.

Parameters
[in]sthe string to be searched.
[in]cthe 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 457 of file Utility.hpp.

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

◆ 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
ExtTthe type of the objects in the binary stream (external).
IntTthe type of the objects in the array (internal).
bigendptrue if the external storage format is big-endian.
Parameters
[in]strthe input stream containing the data of type ExtT (external).
[out]arraythe output array of type IntT (internal).
[in]numthe size of the array.
Exceptions
GeographicErrif the data cannot be read.

Definition at line 476 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
ExtTthe type of the objects in the binary stream (external).
IntTthe type of the objects in the array (internal).
bigendptrue if the external storage format is big-endian.
Parameters
[in]strthe input stream containing the data of type ExtT (external).
[out]arraythe output vector of type IntT (internal).
Exceptions
GeographicErrif the data cannot be read.

Definition at line 528 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
ExtTthe type of the objects in the binary stream (external).
IntTthe type of the objects in the array (internal).
bigendptrue if the external storage format is big-endian.
Parameters
[out]strthe output stream for the data of type ExtT (external).
[in]arraythe input array of type IntT (internal).
[in]numthe size of the array.
Exceptions
GeographicErrif the data cannot be written.

Definition at line 547 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
ExtTthe type of the objects in the binary stream (external).
IntTthe type of the objects in the array (internal).
bigendptrue if the external storage format is big-endian.
Parameters
[out]strthe output stream for the data of type ExtT (external).
[in]arraythe input vector of type IntT (internal).
Exceptions
GeographicErrif the data cannot be written.

Definition at line 594 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]linethe input line.
[out]keythe key.
[out]valthe value.
Exceptions
std::bad_allocif 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.

Referenced by GeographicLib::GravityModel::GravityModel(), and GeographicLib::MagneticModel::MagneticModel().

◆ set_digits()

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

Set the binary precision of a real number.

Parameters
[in]ndigitsthe 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.

References GeographicLib::Math::set_digits().

Referenced by main().

◆ val() [2/2]

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

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

Definition at line 648 of file Utility.hpp.


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