Loading...
Searching...
No Matches
GeographicLib::Utility Class Reference

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;
}
}
main
int main(int argc, const char *const argv[])
Definition CartConvert.cpp:28
Utility.hpp
Header for GeographicLib::Utility class.
GeographicLib
Namespace for GeographicLib.
Definition Accumulator.cpp:12
std
Definition NearestNeighbor.hpp:806

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.

References val().

## 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::GARS::Forward(), GeographicLib::Geohash::Forward(), GeographicLib::Georef::Forward(), GeographicLib::MGRS::Forward(), GeographicLib::UTMUPS::Forward(), GeographicLib::GeoCoords::GeoRepresentation(), GeographicLib::OSGB::GridReference(), main(), 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.

Referenced by date(), main(), and GeographicLib::GeoCoords::Reset().

## 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.

Referenced by main().

## 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.

This routine is used to read binary data files for the Geoid, GravityModel, and MagneticModel classes. In the case of GravityModel and MagneticMode, the data is published by a government agency as text files, and the coefficient to realize the models are converted to a double precision binary format to minimize storage and to simplify reading the data.

For GEOGRAPHIC_PRECISION == 2, the data is read faithfully. For GEOGRAPHICLIB_PRECISION > 2, external data of type double is interpreted as an approximation of an exact decimal value; this exact number is convered to a real number at the higher precision.

Definition at line 333 of file Utility.hpp.

Referenced by GeographicLib::Geoid::CacheArea(), and GeographicLib::SphericalEngine::coeff::readcoeffs().

## 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 450 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 468 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 515 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). If GEOGRAPHICLIB_PRECISION > 5, then the precision is set to GEOGRAPHICLIB_PRECISION, the compile-time value, and ndigits is ignored.

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

Definition at line 184 of file Utility.cpp.

References GeographicLib::Math::set_digits().

Referenced by main().

## 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 595 of file Utility.hpp.

References trim().

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

- Utility.hpp
- Utility.cpp