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

Classes
class	supernovas::Angle
	A representation of a regularized angle, which can be expressed in various commonly used angular units as needed. More...
class	supernovas::Constant
	Various physical constants that SuperNOVAS uses for astrometric calculations, all expressed in terms of SI units. More...
class	supernovas::Coordinate
	A scalar coordinate or distance between two points in space. More...
class	supernovas::Equinox
	Equatorial coordinate system, defining the orientation of the equator and the location of the equinox, relative to which the right ascention and declination (RA/Dec) coordinates are defined. More...
class	supernovas::Interval
	A signed time interval between two instants of time, in the astronomical timescale of choice. More...
class	supernovas::Orbital
	Keplerian orbital elements, for example, for a comet using parameters published by the IAU Minor Planet Center. More...
class	supernovas::OrbitalSystem
	Orbital system for Keplerian orbitals, defining the orbital plane and orientation, and the central body (such as the Sun or a planet), around which the Keplerian orbital is to be defined. More...
class	supernovas::Pressure
	A physical pressure value, which can be instantiated, and then expressed, in different commonly used pressure units (kPa, mbar, torr, atm, and more). More...
class	supernovas::ScalarVelocity
	A scalar velocity (if signed) or speed (unsigned). More...
class	supernovas::Spherical
	Spherical coordinates (longitude, latitude), representing a direction on sky. More...
class	supernovas::Temperature
	A physical temperature value, which can be instantiated, and then expressed, in different commonly used temperature units (C, K, or F). More...
class	supernovas::TimeAngle
	A representation of a regularized angle, which can also be represented as a time value in the 0 to 24h range. More...
class	supernovas::Unit
	Various physical units for converting quantities expressed in conventional units to SI, and vice versa. More...
class	supernovas::Vector
	A generic 3D spatial vector, expressed in arbitrary units. More...

Enumerations
enum	novas_debug_mode { NOVAS_DEBUG_OFF = 0 , NOVAS_DEBUG_ON , NOVAS_DEBUG_EXTRA }
	Settings for 'novas_debug()'. More...

Functions
void	novas_debug (enum novas_debug_mode mode)
	Enables or disables reporting errors and traces to the standard error stream.
enum novas_debug_mode	novas_get_debug_mode ()
	Returns the current, thread-local, mode for reporting errors encountered (and traces).
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).

Detailed Description

Various helpers tools and utilities of the SuperNOVAS library.

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.

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

Since: 1.0

Author: Attila Kovacs

See also: novas_get_debug_mode()

References NOVAS_DEBUG_EXTRA.

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

◆ 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 novas_parse_date_format(), novas_parse_degrees(), novas_parse_hours(), and obs_planets().

◆ 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:

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

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(), novas_parse_iso_date(), and supernovas::Calendar::parse_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:

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

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ novas_debug_mode

Function Documentation

◆ novas_debug()

◆ novas_get_debug_mode()

◆ novas_parse_date()

◆ novas_parse_date_format()

◆ novas_parse_degrees()

◆ novas_parse_dms()

◆ novas_parse_hms()

◆ novas_parse_hours()

◆ novas_parse_iso_date()

◆ novas_parse_timescale()