Loading...
Searching...
No Matches
Helpers and utilities

Various helpers tools and utilities of the SuperNOVAS library. More...

## Macros

#define | NOVAS_ARCMIN (NOVAS_DEGREE / 60.0)
| [rad] An arc minute expressed in radians.
#define | NOVAS_ARCSEC (NOVAS_ARCMIN / 60.0)
| [rad] An arc second expressed in radians.
#define | NOVAS_C 299792458.0
| [m/s] Speed of light in meters/second is a defining physical constant.
#define | NOVAS_DEGREE (M_PI / 180.0)
| [rad] A degree expressed in radians.
#define | NOVAS_HOURANGLE (M_PI / 12.0)
| [rad] An hour of angle expressed in radians.
#define | NOVAS_KM 1000.0
| [m] A kilometer (km) in meters.

## Typedefs

typedef void(* | novas_error_handler) (const char *fmt, va_list args)
| Callback type for the trace / error message handler.

## Enumerations

enum | novas_debug_mode { NOVAS_DEBUG_OFF = 0 , NOVAS_DEBUG_ON , NOVAS_DEBUG_EXTRA }
| Settings for 'novas_debug()'. More...
enum | novas_separator_type { NOVAS_SEP_COLONS = 0 , NOVAS_SEP_SPACES , NOVAS_SEP_UNITS , NOVAS_SEP_UNITS_AND_SPACES }
| Separator type to use for broken-down time/angle string representations in HMS/DMS formats. More...

## Functions

void | novas_debug (enum novas_debug_mode mode)
| Enables or disables reporting errors and traces to the standard error stream.
double | novas_dms_degrees (const char *restrict dms)
| Returns the decimal degrees for a DMS string specification.
int | novas_equ_offset_by (double ra, double dec, double direction, double distance, double *restrict out_ra, double *restrict out_dec)
| Calculates offset equatorial coordinates at some distance away from the input coordinates along a great circle which crosses the input position at the specified position angle.
int | novas_equals_vector (const double *a, const double *b, double tol)
| Checks if two 3D vectors are effectively the same, within the specified absolute tolerance.
enum novas_debug_mode | novas_get_debug_mode ()
| Returns the current, thread-local, mode for reporting errors encountered (and traces).
double | novas_hms_hours (const char *restrict hms)
| Returns the decimal hours for a HMS string specification.
double | novas_norm_ang (double angle)
| Returns the normalized angle in the [0:2π) range.
int | novas_offset_by (double lon, double lat, double direction, double distance, double *restrict out_lon, double *restrict out_lat)
| Calculates offset spherical coordinates at some distance away from the input coordinates along a great circle which crosses the input position at the specified direction.
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 str, char **restrict tail)
| Parses the decimal degrees for a DMS string specification.
double | novas_parse_hms (const char *restrict str, 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).
int | novas_print_dms (double degrees, enum novas_separator_type sep, int decimals, char *restrict buf, int len)
| Prints an angle in degrees as [-]ddd:mm:ss[.S...] into the specified buffer, with up to nanosecond precision.
int | novas_print_hms (double hours, enum novas_separator_type sep, int decimals, char *restrict buf, int len)
| Prints a time in hours as hh:mm:ss[.S...] into the specified buffer, with up to nanosecond precision.
novas_error_handler | novas_set_error_handler (novas_error_handler handler)
| Replaces the trace / error message handler.
double | novas_str_degrees (const char *restrict dms)
| 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 hms)
| Returns a time or time-like angleparsed from a string that contains either a decimal hours or else a broken-down HMS representation.
int | radec2vector (double ra, double dec, double dist, double *restrict pos)
| Converts equatorial spherical coordinates to a vector (equatorial rectangular coordinates).
int | spin (double angle, const double *in, double *out)
| Transforms a vector from one coordinate system to another with same origin and axes rotated about the z-axis.
short | vector2radec (const double *restrict pos, double *restrict ra, double *restrict dec)
| Converts a vector in equatorial rectangular coordinates to equatorial spherical coordinates.

## Detailed Description

Various helpers tools and utilities of the SuperNOVAS library.

## Macro Definition Documentation

## NOVAS_ARCMIN

#define NOVAS_ARCMIN (NOVAS_DEGREE / 60.0)

[rad] An arc minute expressed in radians.

Since
  1.2

## NOVAS_ARCSEC

#define NOVAS_ARCSEC (NOVAS_ARCMIN / 60.0)

[rad] An arc second expressed in radians.

Since
  1.2

Referenced by cio_array().

## NOVAS_C

#define NOVAS_C 299792458.0

[m/s] Speed of light in meters/second is a defining physical constant.

Referenced by novas_set_ssb_vel(), novas_v2z(), novas_z2v(), rad_vel2(), starvectors(), and transform_cat().

## NOVAS_DEGREE

#define NOVAS_DEGREE (M_PI / 180.0)

[rad] A degree expressed in radians.

Since
  1.2

## NOVAS_HOURANGLE

#define NOVAS_HOURANGLE (M_PI / 12.0)

[rad] An hour of angle expressed in radians.

Since
  1.2

Referenced by cio_array().

## NOVAS_KM

#define NOVAS_KM 1000.0

[m] A kilometer (km) in meters.

Since
  1.2

Referenced by novas_make_moon_orbit(), novas_moon_elp_ecl_pos(), and terra().

## Typedef Documentation

## novas_error_handler

typedef void(* novas_error_handler) (const char *fmt, va_list args)

Callback type for the trace / error message handler.

Invoked from the internal tracing helpers (novas_trace(), novas_set_errno(), novas_error(), etc.) whenever the debug mode is not NOVAS_DEBUG_OFF. The default handler writes to stderr via vfprintf().

Replacing the handler lets embedded, WASM, or otherwise freestanding targets redirect error output (or silence it entirely) without paying the cost of stderr.

Parameters

  fmt | printf-style format string, never NULL
  args | variadic argument list matching fmt

Since
  1.7

Author
  Kiran Shila, Attila Kovacs

See also
  novas_set_error_handler(), novas_dfebug()

## Enumeration Type Documentation

## novas_debug_mode

enum novas_debug_mode

Settings for 'novas_debug()'.

See also
  novas_debug()

Enumerator
NOVAS_DEBUG_OFF | Do not print errors and traces to the standard error (default).
NOVAS_DEBUG_ON | Print errors and traces to the standard error.
NOVAS_DEBUG_EXTRA | Print all errors and traces to the standard error, even if they may be acceptable behavior.

## novas_separator_type

enum novas_separator_type

Separator type to use for broken-down time/angle string representations in HMS/DMS formats.

Since
  1.3

See also
  novas_print_hms(), novas_print_dms()

Enumerator
NOVAS_SEP_COLONS | Use colons between components, e.g. '12:34:56'.
NOVAS_SEP_SPACES | Use spaces between components, e.g. '12 34 56'.
NOVAS_SEP_UNITS | Use unit markers after each component, e.g. '12h34m56s'.
NOVAS_SEP_UNITS_AND_SPACES | Useunit markers after each compoent, plus spaces between components, e.g. '12h 34m 56s'.

## Function Documentation

## novas_debug()

void novas_debug | ( | enum novas_debug_mode | mode | ) |

Enables or disables reporting errors and traces to the standard error stream.

Parameters

  mode | NOVAS_DEBUG_OFF (0; or <0), NOVAS_DEBUG_ON (1), or NOVAS_DEBUG_EXTRA (2; or >2).

NOTES:

- This call is not thread-safe. You should avoid calling it from concurrent threads if you want it to have predictable behavior.

Since
  1.0

Author
  Attila Kovacs

See also
  novas_get_debug_mode()

References NOVAS_DEBUG_EXTRA, and NOVAS_DEBUG_OFF.

Referenced by novas_parse_date_format(), novas_parse_degrees(), novas_parse_hours(), and obs_planets().

## 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_equ_offset_by()

int novas_equ_offset_by | ( | double | ra,
|  | double | dec,
|  | double | direction,
|  | double | distance,
|  | double *restrict | out_ra,
|  | double *restrict | out_dec )

Calculates offset equatorial coordinates at some distance away from the input coordinates along a great circle which crosses the input position at the specified position angle.

Parameters

  | ra | [h] reference point right ascension (R.A.)
  | dec | [deg] reference point declination
  | direction | [deg] direction (measured East of North).
  | distance | [deg] offset distance on great circle
  [out] | out_ra | [h] right ascension (R.A.) at offset position in [0:24) range. It may be NULL if not needed.
  [out] | out_dec | [deg] declination at offset position in [-&pi/2:π/2] range. It may be NULL if not needed.

Returns
  0 if successful, or else -1 if very close to the pole, and right ascension (R.A.) at the offset position is requested, or if the input declination is outside of the [-90:90] range.

Since
  1.7

Author
  Attila Kovacs

See also
  novas_offset_by(), novas_equ_sep()

References dec, novas_offset_by(), and ra.

## novas_equals_vector()

int novas_equals_vector | ( | const double * | a,
|  | const double * | b,
|  | double | tol )

Checks if two 3D vectors are effectively the same, within the specified absolute tolerance.

Two vectors are equal if the distance between them is less than or equal to the magnitude of the specified tolerance.

NOTES:

- Two NULL (undefined) vectors are considered not equal.
- A vector may not equal itself if it contains NAN or infinite components, since NAN != NAN and INFINITE != INFINITE.

Parameters

  a | one of the vectors
  b | the other vector
  tol | absolute tolerance (sign is ignored).

Returns
  TRUE (1) if all the two vectors match within the specified tolerance, or else FALSE (0)

Since
  1.7

Author
  Attila Kovacs

Referenced by novas_equals_near_earth(), novas_equals_planet_bundle(), novas_equals_sky_pos(), and novas_equals_ssb_posvel().

## novas_get_debug_mode()

enum novas_debug_mode novas_get_debug_mode | ( |  | ) |

Returns the current, thread-local, mode for reporting errors encountered (and traces).

Returns
  The current debug mode in the calling thread.

Since
  1.0

Author
  Attila Kovacs

See also
  novas_debug()

Referenced by geo_posvel(), novas_parse_date_format(), novas_parse_degrees(), novas_parse_hours(), and obs_planets().

## 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_norm_ang()

double novas_norm_ang | ( | double | angle | ) |

Returns the normalized angle in the [0:2π) range.

Parameters

  angle | [rad] an angle in radians.

Returns
  [rad] the normalized angle in the [0:2π) range.

Since
  1.0

Author
  Attila Kovacs

References TWOPI.

Referenced by fund_args().

## novas_offset_by()

int novas_offset_by | ( | double | lon,
|  | double | lat,
|  | double | direction,
|  | double | distance,
|  | double *restrict | out_lon,
|  | double *restrict | out_lat )

Calculates offset spherical coordinates at some distance away from the input coordinates along a great circle which crosses the input position at the specified direction.

Based on the astropy offset_by() implementation.

Parameters

  | lon | [deg] reference point longitude
  | lat | [deg] reference point latitude
  | direction | [deg] direction (measured East of North).
  | distance | [deg] offset distance on great circle
  [out] | out_lon | [deg] longitude at offset position in [-π:π) range. It may be NULL if not needed.
  [out] | out_lat | [deg] latitude at offset position in [-&pi/2:π/2] range. It may be NULL if not needed.

Returns
  0 if successful, or else -1 if very close to the pole, and longitude at the offset position is requested, or if the input latitude is outside of the [-90:90] range.

Since
  1.7

Author
  Attila Kovacs

See also
  novas_equ_offset_by(), novas_sep()
  https://docs.astropy.org/en/stable/_modules/astropy/coordinates/angles/utils.html#offset_at

Referenced by novas_equ_offset_by().

## novas_parse_date()

double novas_parse_date | ( | const char *restrict | date,
|  | char **restrict | tail )

Parses an astronomical date/time string into a Julian date specification.

The date must be YMD-type with full year, followed the month (numerical or name or 3-letter abbreviation), and the day. The components may be separated by dash -, underscore _, dot ., slash '/', or spaces/tabs, or any combination thereof. The date may be followed by a time specification in HMS format, separated from the date by the letter T or t, or spaces, comma ,, or semicolon ;, or underscore _ or a combination thereof. Finally, the time may be followed by the letter Z, or z (for UTC) or else {+/-}HH[:[MM]] time zone specification.

For example:

2025-01-26
2025 January 26
2025_Jan_26
2025-01-26T19:33:08Z
2025.01.26T19:33:08
2025 1 26 19h33m28.113
2025/1/26 19:33:28+02
2025-01-26T19:33:28-0600
2025 Jan 26 19:33:28+05:30

are all valid dates that can be parsed.

NOTES:

1. This function assumes Gregorian dates after their introduction on 1582 October 15, and Julian/Roman dates before that, as was the convention of the time. I.e., the day before of the introduction of the Gregorian calendar reform is 1582 October 4. I.e., you should not use this function with ISO 8601 timestamps containing dates prior to 1582 October 15 (for such date you may use novas_parse_iso_date() instead).
2. B.C. dates are indicated with years <=0 according to the astronomical and ISO 8601 convention, i.e., X B.C. as (1-X), so 45 B.C. as -44.

Parameters

  | date | The astronomical date specification, possibly including time and timezone, in a standard format. The date is assumed to be in the astronomical calendar of date, which differs from ISO 8601 timestamps for dates prior to the Gregorian calendar reform of 1582 October 15 (otherwise, the two are identical).
  [out] | tail | (optional) If not NULL it will be set to the next character in the string after the parsed time.

Returns
  [day] The Julian Day corresponding to the string date/time specification or NAN if the string is NULL or if it does not specify a date/time in the expected format.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_parse_iso_date(), novas_parse_date_format(), novas_date(), novas_date_scale(), novas_timescale_for_string(), novas_iso_timestamp(), novas_timestamp()

References NOVAS_ASTRONOMICAL_CALENDAR, novas_parse_date_format(), and NOVAS_YMD.

Referenced by novas_date(), novas_date_scale(), and novas_set_str_time().

## novas_parse_date_format()

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

The date must be composed of a full year (e.g. 2025), a month (numerical or name or 3-letter abbreviation, e.g. "01", "1", "January", or "Jan"), and a day (e.g. "08" or "8"). The components may be separated by dash -, underscore _, dot ., slash '/', or spaces/tabs, or any combination thereof. The components will be parsed in the specified order.

The date may be followed by a time specification in HMS format, separated from the date by the letter T or t, or spaces, comma ,, or semicolon ; or underscore '_', or a combination thereof. Finally, the time may be followed by the letter Z, or z (for UTC) or else by a {+/-}HH[:[MM]] time zone specification.

For example, for format NOVAS_YMD, all of the following strings may specify the date:

2025-01-26
2025 January 26
2025_Jan_26
2025-01-26T19:33:08Z
2025.01.26T19:33:08
2025 1 26 19h33m28.113
2025/1/26 19:33:28+02
2025-01-26T19:33:28-0600
2025 Jan 26 19:33:28+05:30

are all valid dates that can be parsed.

If your date format cannot be parsed with this function, you may parse it with your own function into year, month, day, and decimal hour-of-day components, and use julian_date() with those.

NOTES:

1. B.C. dates are indicated with years <=0 according to the astronomical and ISO 8601 convention, i.e., X B.C. as (1-X), so 45 B.C. as -44.

Parameters

  | calendar | The type of calendar to use: NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, or NOVAS_ROMAN_CALENDAR.
  | format | Expected order of date components: NOVAS_YMD, NOVAS_DMY, or NOVAS_MDY.
  | date | The date specification, possibly including time and timezone, in the specified standard format.
  [out] | tail | (optional) If not NULL it will be set to the next character in the string after the parsed time.

Returns
  [day] The Julian Day corresponding to the string date/time specification or NAN if the string is NULL or if it does not specify a date/time in the expected format.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_parse_date(), novas_parse_iso_date(), novas_timescale_for_string(), novas_iso_timestamp() novas_jd_from_date()

References novas_debug(), NOVAS_DEBUG_OFF, NOVAS_DMY, novas_get_debug_mode(), novas_jd_from_date(), NOVAS_MDY, novas_parse_hms(), and NOVAS_YMD.

Referenced by novas_parse_date(), and novas_parse_iso_date().

## novas_parse_degrees()

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.

The decimal representation may be followed by a unit designator: "d", "dg", "deg", "degree", or "degrees", which will be parsed case-insensitively also, if present.

Both DMS and decimal values may start or end with a compass direction: such as an upper-case letter N, E, S, or W, or else the case-insensitive words 'North', 'East', 'South' or 'West'.

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.

A few examples of angles that may be parsed:

-179:59:59.999
-179d 59m 59.999s
179 59' 59.999" S
179 59 S
-179.99999d
-179.99999
179.99999W
179.99999 West
179.99999 deg S
W 179.99999d
North 179d 59m
east 179.99 degrees

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 followed by the letter d immediately. And both the decimal and DMS representation may be ended with a compass direction marker, N, E, S, or W. See more in novas_parse_dms() on acceptable DMS specifications.
  [out] | tail | (optional) If not NULL it will be set to the next character in the string after the parsed angle.

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_str_degrees(), novas_parse_dms(), novas_parse_hours()

References novas_debug(), NOVAS_DEBUG_OFF, novas_get_debug_mode(), and novas_parse_dms().

Referenced by novas_str_degrees().

## novas_parse_dms()

double novas_parse_dms | ( | const char *restrict | dms,
|  | char **restrict | tail )

Parses the decimal degrees for a DMS string specification.

The degree, (arc)minute, and (arc)second components may be separated by spaces, tabs, colons :, underscore _, 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 a 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
179 59 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.

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.
  [out] | tail | (optional) If not NULL it will be set to the next character in the string after the parsed time.

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_dms_degrees(), novas_parse_degrees(), novas_print_dms(), novas_parse_hms()

Referenced by novas_dms_degrees(), and novas_parse_degrees().

## novas_parse_hms()

double novas_parse_hms | ( | const char *restrict | hms,
|  | char **restrict | tail )

Parses the decimal hours for a HMS string specification.

The hour, minute, and second components may be separated by spaces, tabs, colons :, underscore _, 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 are valid specifications:

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

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.

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.
  [out] | tail | (optional) If not NULL it will be set to the next character in the string after the parsed time.

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_hms_hours(), novas_parse_hours(), novas_print_hms(), novas_parse_dms()

Referenced by novas_hms_hours(), novas_parse_date_format(), and novas_parse_hours().

## novas_parse_hours()

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.

The decimal representation may be followed by a unit designator: "h", "hr", "hrs", "hour", or "hours", which will be parsed case-insensitively also, if present.

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.

A few examples of angles that may be parsed:

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

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_hms() on acceptable HMS input specifications.
  [out] | tail | (optional) If not NULL it will be set to the next character in the string after the parsed angle.

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_str_hours(), novas_parse_hms(), novas_parse_degrees()

References novas_debug(), NOVAS_DEBUG_OFF, novas_get_debug_mode(), and novas_parse_hms().

Referenced by novas_str_hours().

## novas_parse_iso_date()

double novas_parse_iso_date | ( | const char *restrict | date,
|  | char **restrict | tail )

Parses an ISO 8601 timestamp, converting it to a Julian day.

It is equivalent to novas_parse_date() for dates after the Gregorian calendar reform of 1582. For earlier dates, ISO timestamps continue to assume the Gregorian calendar (i.e. proleptic Gregorian dates), whereas novas_parse_timestamp() will assume Roman/Julian dates, which were conventionally used before the calendar reform.

NOTES:

1. B.C. dates are indicated with years <=0 according to the astronomical and ISO 8601 convention, i.e., X B.C. as (1-X), so 45 B.C. as -44.

Parameters

  | date | The ISO 8601 date specification, possibly including time and timezone, in a standard format.
  [out] | tail | (optional) If not NULL it will be set to the next character in the string after the parsed time.

Returns
  [day] The Julian Day corresponding to the string date/time specification or NAN if the string is NULL or if it does not specify a date/time in the expected format.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_iso_timestamp(), novas_parse_date()

References NOVAS_GREGORIAN_CALENDAR, novas_parse_date_format(), and NOVAS_YMD.

## novas_parse_timescale()

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

The following timescale values are recognised: "UTC", "UT", "UT0", "UT1", "GMT", "TAI", "GPS", "TT", "ET", "TCG", "TCB", "TDB".

Parameters

  | str | String specifying an astronomical timescale. Leading white spaces will be skipped over.
  [out] | tail | (optional) If not NULL it will be set to the next character in the string after the parsed timescale specification.

Returns
  The SuperNOVAS timescale constant (<=0), or else -1 if the string was NULL, empty, or could not be matched to a timescale value (errno will be set to EINVAL also).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_timescale_for_string(), novas_set_str_time(), novas_print_timescale()

References novas_timescale_for_string(), and NOVAS_UTC.

Referenced by novas_date_scale().

## novas_print_dms()

int novas_print_dms | ( | double | degrees,
|  | enum novas_separator_type | sep,
|  | int | decimals,
|  | char *restrict | buf,
|  | int | len )

Prints an angle in degrees as [-]ddd:mm:ss[.S...] into the specified buffer, with up to nanosecond precision.

The degrees component is always printed as 4 characters (up to 3 digits plus optional negative sign), so the output is always aligned. If positive values are expected to be explicitly signed also, the caller may simply put the '+' sign into the leading byte.

NaN and infinite values, are printed as their standard floating-point representations.

Parameters

  | degrees | [deg] angle value
  | sep | Type of separators to use between or after components. If the separator value is outside of the enum range, it will default to using colons.
  | decimals | Requested number of decimal places to print for the seconds [0:9].
  [out] | buf | String buffer in which to print DMS string, represented in the [-180:180) degree range.
  | len | Maximum number of bytes that may be written into the output buffer, including termination.

Returns
  The number of characters actually printed in the buffer, excluding termination, or else -1 if the input buffer is NULL or the length is less than 1 (errno will be set to EINVAL).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_parse_dms(), novas_print_hms()

References NOVAS_SEP_COLONS, NOVAS_SEP_SPACES, NOVAS_SEP_UNITS, and NOVAS_SEP_UNITS_AND_SPACES.

## novas_print_hms()

int novas_print_hms | ( | double | hours,
|  | enum novas_separator_type | sep,
|  | int | decimals,
|  | char *restrict | buf,
|  | int | len )

Prints a time in hours as hh:mm:ss[.S...] into the specified buffer, with up to nanosecond precision.

NaN and infinite values, are printed as their standard floating-point representations.

Parameters

  | hours | [h] time value
  | sep | Type of separators to use between or after components. If the separator value is outside of the enum range, it will default to using colons.
  | decimals | Requested number of decimal places to print for the seconds [0:9].
  [out] | buf | String buffer in which to print HMS string, represented in the [0:24) hour range.
  | len | Maximum number of bytes that may be written into the output buffer, including termination.

Returns
  The number of characters actually printed in the buffer, excluding termination, or else -1 if the input buffer is NULL or the length is less than 1 (errno will be set to EINVAL).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_parse_hms(), novas_print_dms(), novas_timestamp()

References NOVAS_SEP_COLONS, NOVAS_SEP_SPACES, NOVAS_SEP_UNITS, and NOVAS_SEP_UNITS_AND_SPACES.

## novas_set_error_handler()

novas_error_handler novas_set_error_handler | ( | novas_error_handler | handler | ) |

Replaces the trace / error message handler.

Pass NULL to restore the default error reporting to stderr. Or, to silence error output entirely, use novas_debug(NOVAS_DEBUG_OFF).

When built with WITHOUT_LIBC there is no default stderr handler, so passing NULL silences output entirely (same effect as novas_debug(NOVAS_DEBUG_OFF)).

NOTES:

- This call is not thread-safe. You should avoid calling it from concurrent threads if you want it to have predictable behavior.

Parameters

  handler | new handler, or NULL to restore the default error messaging to stderr (or to silence output when built with WITHOUT_LIBC).

Returns
  the previous handler (so it can be restored or chained)

Since
  1.7

Author
  Kiran Shila, Attila Kovacs

See also
  novas_debug()

References DEFAULT_ERROR_HANDLER.

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

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

## radec2vector()

int radec2vector | ( | double | ra,
|  | double | dec,
|  | double | dist,
|  | double *restrict | pos )

Converts equatorial spherical coordinates to a vector (equatorial rectangular coordinates).

Parameters

  | ra | [h] Right ascension (hours).
  | dec | [deg] Declination (degrees).
  | dist | [AU] Distance (AU)
  [out] | pos | [AU] Position 3-vector, equatorial rectangular coordinates (AU).

Returns
  0 if successful, or -1 if the vector argument is NULL.

See also
  vector2radec(), starvectors()

References dec, and ra.

Referenced by earth_sun_calc(), gcrs2equ(), novas_app_to_geom(), novas_app_to_hor(), novas_lsr_to_ssb_vel(), novas_ssb_to_lsr_vel(), starvectors(), and transform_cat().

## spin()

int spin | ( | double | angle,
|  | const double * | in,
|  | double * | out )

Transforms a vector from one coordinate system to another with same origin and axes rotated about the z-axis.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.

Parameters

  | angle | [deg] Angle of coordinate system rotation, positive counterclockwise when viewed from +z, in degrees.
  | in | Input position vector.
  [out] | out | Position vector expressed in new coordinate system rotated about z by 'angle'. It can be the same vector as the input.

Returns
  0 if successful, or -1 if the output vector is NULL.

References in, out, and TWOPI.

Referenced by cel2ter(), cirs_to_tod(), novas_app_to_geom(), novas_app_to_hor(), novas_hor_to_app(), place(), ter2cel(), and tod_to_cirs().

## vector2radec()

short vector2radec | ( | const double *restrict | pos,
|  | double *restrict | ra,
|  | double *restrict | dec )

Converts a vector in equatorial rectangular coordinates to equatorial spherical coordinates.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.

Parameters

  | pos | Position 3-vector, equatorial rectangular coordinates.
  [out] | ra | [h] Right ascension in hours [0:24] or NAN if the position vector is NULL or a null-vector. It may be NULL if not required.
  [out] | dec | [deg] Declination in degrees [-90:90] or NAN if the position vector is NULL or a null-vector. It may be NULL if not required.

Returns
  0 if successful, -1 of any of the arguments are NULL, or 1 if all input components are 0 so 'ra' and 'dec' are indeterminate, or else 2 if both x and y are zero, but z is nonzero, and so 'ra' is indeterminate.

See also
  radec2vector()

References dec, and ra.

Referenced by gcrs2equ(), mean_star(), novas_geom_to_app(), novas_hor_to_app(), novas_moon_elp_sky_pos_fp(), novas_moon_phase(), novas_transform_sky_pos(), novas_uvw(), and place().