Loading...
Searching...
No Matches
parse.c File Reference

Various functions to parse string specifications of angles, time, dates, and coordinate epochs. More...

## Functions

double | novas_dms_degrees (const char *restrict dms)
| Returns the decimal degrees for a DMS string specification.
double | novas_epoch (const char *restrict system)
| Returns the Julian day corresponding to an astronomical coordinate epoch.
double | novas_hms_hours (const char *restrict hms)
| Returns the decimal hours for a HMS string specification.
double | novas_parse_date (const char *restrict date, char **restrict tail)
| Parses an astronomical date/time string into a Julian date specification.
double | novas_parse_date_format (enum novas_calendar_type calendar, enum novas_date_format format, const char *restrict date, char **restrict tail)
| Parses a calendar date/time string, expressed in the specified type of calendar, into a Julian day (JD).
double | novas_parse_degrees (const char *restrict str, char **restrict tail)
| Parses an angle in degrees from a string that contains either a decimal degrees or else a broken-down DMS representation.
double | novas_parse_dms (const char *restrict dms, char **restrict tail)
| Parses the decimal degrees for a DMS string specification.
double | novas_parse_hms (const char *restrict hms, char **restrict tail)
| Parses the decimal hours for a HMS string specification.
double | novas_parse_hours (const char *restrict str, char **restrict tail)
| Parses a time or time-like angle from a string that contains either a decimal hours or else a broken-down HMS representation.
double | novas_parse_iso_date (const char *restrict date, char **restrict tail)
| Parses an ISO 8601 timestamp, converting it to a Julian day.
enum novas_timescale | novas_parse_timescale (const char *restrict str, char **restrict tail)
| Parses the timescale from a string containing a standard abbreviation (case insensitive), and returns the updated parse position after the timescale specification (if any).
double | novas_str_degrees (const char *restrict str)
| Returns an angle parsed from a string that contains either a decimal degrees or else a broken-down DMS representation.
double | novas_str_hours (const char *restrict str)
| Returns a time or time-like angleparsed from a string that contains either a decimal hours or else a broken-down HMS representation.
enum novas_timescale | novas_timescale_for_string (const char *restrict str)
| Returns the timescale constant for a string that denotes the timescale in with a standard abbreviation (case insensitive).

## Detailed Description

Various functions to parse string specifications of angles, time, dates, and coordinate epochs.

Date
  Created on Mar 2, 2025

Author
  Attila Kovacs

See also
  target.c, observer.c, timescale.c

## Function Documentation

## novas_dms_degrees()

double novas_dms_degrees | ( | const char *restrict | dms | ) |

Returns the decimal degrees for a DMS string specification.

The degree, (arc)minute, and (arc)second components may be separated by spaces, tabs, colons :, or a combination thereof. Additionally, the degree and minutes may be separated by the letter d, and the minutes and seconds may be separated by m or a single quote '. The seconds may be followed by 's' or double quote ". Finally, the leading or trailing component may additionally be a standalone upper-case letter 'N', 'E', 'S', or 'W' or the words 'North', 'East', 'South', or 'West' (case insensitive), signifying a compass direction.

There is no enforcement on the range of angles that can be represented in this way. Any finite angle is parseable, even if it is outside its conventional range, such as +- 90 degrees N/S.

For example, all of the lines below are valid specifications:

-179:59:59.999
-179d 59m 59.999s
-179 59' 59.999
179:59:59.999S
179 59 59.999 W
179 59 59.999 west
179_59_59.999__S
W 179 59 59
North 179d 59m

At least the leading two components (degrees and arcminutes) are required. If the arcseconds are ommitted, they will be assumed zero, i.e. 179:59 is the same as 179:59:00.000.

NOTES:

1. To see if the string was fully parsed when returning a valid (non-NAN) value, you can check errno: it should be zero (0) if all non-whitespace characters have been parsed from the input string, or else EINVAL if the parsed value used only the leading part of the string.

Parameters

  dms | String specifying degrees, minutes, and seconds, which correspond to an angle. Angles in any range are permitted, but the minutes and seconds must be >=0 and <60.

Returns
  [deg] Corresponding decimal angle value, or else NAN if there was an error parsing the string (errno will be set to EINVAL).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_str_degrees(), novas_parse_dms(), novas_hms_hours()

References novas_parse_dms().

## novas_epoch()

double novas_epoch | ( | const char *restrict | system | ) |

Returns the Julian day corresponding to an astronomical coordinate epoch.

Parameters

  system | Coordinate system, e.g. "ICRS", "B1950.0", "J2000.0", "FK4", "FK5", "1950", "2000", or "HIP". In general, any Besselian or Julian year epoch can be used by year (e.g. "B1933.193" or "J2022.033"), or else the fixed values listed. If 'B' or 'J' is ommitted in front of the epoch year, then Besselian epochs are assumed prior to 1984.0, and Julian epochs after.

Returns
  [day] The Julian day corresponding to the given coordinate epoch, or else NAN if the input string is NULL or the input is not recognised as a coordinate epoch specification (errno will be set to EINVAL).

Since
  1.3

Author
  Attila Kovacs

See also
  make_cat_object_sys(), make_redshifted_object_sys(), transform_cat(), precession()
  NOVAS_SYSTEM_ICRS, NOVAS_SYSTEM_B1950, NOVAS_SYSTEM_J2000, NOVAS_SYSTEM_HIP

References NOVAS_BESSELIAN_YEAR_DAYS, NOVAS_JD_B1950, NOVAS_JD_HIP, NOVAS_JD_J2000, NOVAS_JULIAN_YEAR_DAYS, NOVAS_SYSTEM_FK4, NOVAS_SYSTEM_FK5, NOVAS_SYSTEM_FK6, and NOVAS_SYSTEM_HIP.

Referenced by supernovas::Equinox::from_string().

## novas_hms_hours()

double novas_hms_hours | ( | const char *restrict | hms | ) |

Returns the decimal hours for a HMS string specification.

The hour, minute, and second components may be separated by spaces, tabs, colons :, or a combination thereof. Additionally, the hours and minutes may be separated by the letter h, and the minutes and seconds may be separated by m or a single quote '. The seconds may be followed by 's' or double quote ".

There is no enforcement on the range of hours that can be represented in this way. Any finite angle is parseable, even if it is outside its conventional range of 0-24h.

For example, all of the lines below specify the same time:

23:59:59.999
23h 59m 59.999s
23h59'59.999
23 59 59.999
23 59
23h

At least the leading two components (hours and minutes) are required. If the seconds are ommitted, they will be assumed zero, i.e. 23:59 is the same as 23:59:00.000.

NOTES:

1. To see if the string was fully parsed when returning a valid (non-NAN) value, you can check errno: it should be zero (0) if all non-whitespace characters have been parsed from the input string, or else EINVAL if the parsed value used only the leading part of the string.

Parameters

  hms | String specifying hours, minutes, and seconds, which correspond to a time between 0 and 24 h. Time in any range is permitted, but the minutes and seconds must be >=0 and <60.

Returns
  [hours] Corresponding decimal time value, or else NAN if there was an error parsing the string (errno will be set to EINVAL).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_str_hours(), novas_parse_hms(), novas_dms_degrees()

References novas_parse_hms().

## novas_str_degrees()

double novas_str_degrees | ( | const char *restrict | str | ) |

Returns an angle parsed from a string that contains either a decimal degrees or else a broken-down DMS representation.

See novas_parse_degrees() to see what string representations may be used.

To see if the string was fully parsed when returning a valid (non-NAN) value, you can check errno: it should be zero (0) if all non-whitespace and punctuation characters have been parsed from the input string, or else EINVAL if the parsed value used only the leading part of the string.

Parameters

  str | The input string that specified an angle either as decimal degrees or as a broken down DMS speficication. The decimal value may be immediately followed by a letter 'd'. See more in novas_parse_degrees() on acceptable input specifications.

Returns
  [deg] The angle represented by the string, or else NAN if the string could not be parsed into an angle value (errno will indicate the type of error).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_parse_degrees(), novas_parse_dms(), novas_print_dms(), novas_str_hours()

References novas_parse_degrees().

Referenced by supernovas::Angle::Angle().

## novas_str_hours()

double novas_str_hours | ( | const char *restrict | str | ) |

Returns a time or time-like angleparsed from a string that contains either a decimal hours or else a broken-down HMS representation.

See novas_parse_hours() to see what string representations may be used.

To check if the string was fully parsed when returning a valid (non-NAN) value you can check errno: it should be zero (0) if all non-whitespace and punctuation characters have been parsed from the input string, or else EINVAL if the parsed value used only the leading part of the string.

Parameters

  str | The input string that specified an angle either as decimal hours or as a broken down HMS speficication. The decimal value may be immediately followed by a letter 'h'. See more in novas_parse_hours() on acceptable input specifications.

Returns
  [h] The time-like value represented by the string, or else NAN if the string could not be parsed into a time-like value (errno will indicate the type of error).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_parse_hours(), novas_parse_hms(), novas_print_hms(), novas_str_degrees()

References novas_parse_hours().

Referenced by supernovas::TimeAngle::TimeAngle().