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:29
Utility.hpp
Header for GeographicLib::Utility class.
GeographicLib::Utility::day
static int day(int y, int m=1, int d=1)
Definition: Utility.cpp:22
GeographicLib
Namespace for GeographicLib.
Definition: Accumulator.cpp:12
std
Definition: NearestNeighbor.hpp:812

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

inline static

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

inline static

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

inline static

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`
| ) |  |

inline static

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

inline static

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

inline static

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

inline static

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

inline static

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

inline static

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

inline static

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

inline static

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

inline static

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:

- Utility.hpp
- Utility.cpp