Macros
#define	MAX_DECIMALS 9
	Maximum decimal places for seconds in HMS/DMS formats.

Functions
double	novas_dms_degrees (const char *restrict dms)

double	novas_epoch (const char *restrict system)

double	novas_hms_hours (const char *restrict hms)

double	novas_parse_degrees (const char restrict str, char *restrict tail)

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

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

double	novas_parse_hours (const char restrict str, char *restrict tail)

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

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

double	novas_str_degrees (const char *restrict str)

double	novas_str_hours (const char *restrict str)

Detailed Description

Date: Created on Mar 2, 2025

Author: Attila Kovacs

Various functions to parse string values for SuperNOVAS.

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:

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.

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_JD_B1950, NOVAS_JD_HIP, NOVAS_JD_J2000, NOVAS_SYSTEM_FK4, NOVAS_SYSTEM_FK5, NOVAS_SYSTEM_HIP, and NOVAS_SYSTEM_ICRS.

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

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

◆ 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 bysor 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()

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

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

◆ 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 MAX_DECIMALS, 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 MAX_DECIMALS, NOVAS_SEP_COLONS, NOVAS_SEP_SPACES, NOVAS_SEP_UNITS, and NOVAS_SEP_UNITS_AND_SPACES.

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

Macros

Functions

Detailed Description

Function Documentation

◆ novas_dms_degrees()

◆ novas_epoch()

◆ novas_hms_hours()

◆ novas_parse_degrees()

◆ novas_parse_dms()

◆ novas_parse_hms()

◆ novas_parse_hours()

◆ novas_print_dms()

◆ novas_print_hms()

◆ novas_str_degrees()

◆ novas_str_hours()