skyio.h - output and formatting routines and a read routine More...

Macros
#define	NO_ANGLE (-1)

#define	INVALID_ANGLE (-2)

Functions
char *	skyio_degToDmsStr (char destStr[], size_t destStrSize, double angle_deg, unsigned decimals)
	Routine to take an angle in degrees and return a string of the form [±]DDD°MM′SS.sss″ correctly rounding according to the number of decimal places to be shown. More...

char *	skyio_hrsToHmsStr (char destStr[], size_t destStrSize, double angle_h, unsigned decimals)
	Routine to take an angle in hours and return a string in hours, minutes and seconds form - "±HH:MM:SS.sss" - correctly rounding according to the number of decimal places to be shown. More...

double	skyio_sxStrToAng (const char angleStr[], const char *endPtr, int error)
	Convert a string containing an angle (or a time) in sexagesimal format to the angle's value. More...

static char *	skyio_radToDmsStr (char destStr[], size_t destStrSize, double angle_rad, unsigned decimals)
	Routine to take an angle in radian and return a string in degrees, arcminutes and arcseconds form - [±]DDD°MM′SS.sss″ - correctly rounding according to the number of decimal places to be shown. More...

static char *	skyio_radToHmsStr (char destStr[], size_t destStrSize, double angle_rad, unsigned decimals)
	Routine to take an angle in radian and return a string in hours, minutes and seconds form - "±HH:MM:SS.sss" - correctly rounding according to the number of decimal places to be shown. More...

void	skyio_printJ2kd (double j2kd)
	Write out a J2KD as a calendar date and time. More...

Detailed Description

skyio.h - output and formatting routines and a read routine

Author: David Hoadley

Routines for reading and writing out assorted astronomical things, such as:

formatting a radian angle, or an angle expressed in hours, into a string in Hours Minutes Seconds form, something only an astronomer would think of doing.
formatting a radian angle, or an angle expressed in degrees into a string in Degrees Minutes Seconds form, and doing it correctly. Quite a few people need this one.
reading an angle from a string
write out a Julian Date (in J2KD form - see Time variables) as a calendar date and time.

These routines were mainly developed for debugging.

Definition in file skyio.h.

Function Documentation

◆ skyio_degToDmsStr()

char* skyio_degToDmsStr	(	char	destStr[],
		size_t	destStrSize,
		double	angle_deg,
		unsigned	decimals
	)

Routine to take an angle in degrees and return a string of the form [±]DDD°MM′SS.sss″ correctly rounding according to the number of decimal places to be shown.

The angle is assumed to be within the range (-360.0, 360.0). Angles which round to ±360° will be written out as 0°.

Returns: Pointer to destStr

Parameters

[out]	destStr	Destination character string
[in]	destStrSize	Size of destination string (max available length + 1)
[in]	angle_deg	The angle to be written out (degrees). Valid range:(-360, 360); larger numbers may well be written OK, but there is a risk of overflowing an intermediate variable. No error will be detected, just a wrong answer will be written.
[in]	decimals	Number of digits after the decimal point to display. Valid range: [0,9] (or [0,3] if long int is only a 32-bit number); numbers outside this range will be clamped to this range.

Definition at line 88 of file skyio.c.

◆ skyio_hrsToHmsStr()

char* skyio_hrsToHmsStr	(	char	destStr[],
		size_t	destStrSize,
		double	angle_h,
		unsigned	decimals
	)

Routine to take an angle in hours and return a string in hours, minutes and seconds form - "±HH:MM:SS.sss" - correctly rounding according to the number of decimal places to be shown.

The angle is assumed to be within the range (-24.0, 24.0). Angles which round to ±24:00:00 will be written out as 0:00:00.

Returns: Pointer to destStr

Parameters

[out]	destStr	Destination character string
[in]	destStrSize	Size of destination string (max available length + 1)
[in]	angle_h	The angle to be written out (hours). Valid range:(-24.0, 24.0); larger numbers may well be written OK, but there is a risk of overflowing an intermediate variable. No error will be detected, just a wrong answer will be written.
[in]	decimals	Number of digits after the decimal point to display. Valid range: [0,9] (or [0,3] if long int is only a 32-bit number); numbers outside this range will be clamped to this range.

Definition at line 193 of file skyio.c.

◆ skyio_sxStrToAng()

double skyio_sxStrToAng	(	const char	angleStr[],
		const char **	endPtr,
		int *	error
	)

Convert a string containing an angle (or a time) in sexagesimal format to the angle's value.

The field containing the angle consists of either one subfield (decimal degrees or hours), two subfields (degrees and arcminutes or hours and minutes) three subfields (degrees, arcminutes and arcseconds or hours minutes and seconds). The location of the decimal point (if any) is what determines how many subfields are present. The following are all examples of valid angles (or times):

21.625 or +21.625°
-21 37.5 or 21:37.5 or -21°37.5′ or 21h37.5m
+21 37 30 or 21:37:30.0 or -21°37′30.0″

If the string contains degrees, minutes and seconds, the result will be in degrees. If the string contains hours, minutes and seconds, the result will be in hours.

The routine will accept almost anything appearing between the numbers, such as °, ′, & ″; or d, ' & "; or h, m, & s; or colons or spaces or tabs. These are ignored and are not checked for whether they make sense or not.

Returns: The angle or time

Parameters

[in]	angleStr	The string of text containing the angle
[out]	endPtr	A pointer to the end of that part of angleStr that was read to obtain the number. This may be pointing to some white space between the number just decoded and further data, or it may be the end of the string. A NULL pointer may be passed to this parameter if you do not need this value.
[out]	error	What errors were detected during decoding? This is set to NO_ANGLE (-1) if no value was found in the string. It is set to INVALID_ANGLE (-2) if the minutes or seconds fields are outside the range [0.0, 60.0). A NULL pointer may be passed to this parameter if you do not care about the conversion status.

Definition at line 288 of file skyio.c.

◆ skyio_radToDmsStr()

static char* skyio_radToDmsStr	(	char	destStr[],
		size_t	destStrSize,
		double	angle_rad,
		unsigned	decimals
	)

inlinestatic

Routine to take an angle in radian and return a string in degrees, arcminutes and arcseconds form - [±]DDD°MM′SS.sss″ - correctly rounding according to the number of decimal places to be shown.

The angle is assumed to be within the range (-2*Pi, 2*Pi). Angles which round to ±360° will be written out as 0°.

Returns: Pointer to destStr

Parameters

[out]	destStr	Destination character string
[in]	destStrSize	Size of destination string (max available length + 1)
[in]	angle_rad	The angle to be written out (radian). Valid range:(-2Pi, 2Pi); larger numbers may well be written OK, but there is a risk of overflowing an intermediate variable. No error will be detected, just a wrong answer will be written.
[in]	decimals	Number of digits after the decimal point to display. Valid range: [0,9] (or [0,3] if long int is only a 32-bit number); numbers outside this range will be clamped to this range.

Examples: demo1_sun.c, demo2_sun_tracking.c, demo3_moon.c, and demo4_multiple_sites.c.

Definition at line 111 of file skyio.h.

◆ skyio_radToHmsStr()

static char* skyio_radToHmsStr	(	char	destStr[],
		size_t	destStrSize,
		double	angle_rad,
		unsigned	decimals
	)

inlinestatic

Routine to take an angle in radian and return a string in hours, minutes and seconds form - "±HH:MM:SS.sss" - correctly rounding according to the number of decimal places to be shown.

The angle is assumed to be within the range (-2*Pi, 2*Pi). Angles which round to ±24:00:00 will be written out as 0:00:00.

Returns: Pointer to destStr

Parameters

[out]	destStr	Destination character string
[in]	destStrSize	Size of destination string (max available length + 1)
[in]	angle_rad	The angle to be written out (radian). Valid range:(-2Pi, 2Pi); larger numbers may well be written OK, but there is a risk of overflowing an intermediate variable. No error will be detected, just a wrong answer will be written.
[in]	decimals	Number of digits after the decimal point to display. Valid range: [0,9] (or [0,3] if long int is only a 32-bit number); numbers outside this range will be clamped to this range.

Definition at line 146 of file skyio.h.

◆ skyio_printJ2kd()

void skyio_printJ2kd ( double j2kd )

Write out a J2KD as a calendar date and time.

The date and time are written in ISO format, separated by a space. Time is written to three decimal places of seconds. No newline is written at the end.

Parameters

[in] j2kd The date/time in J2KD format.

Examples: demo1_sun.c, demo2_sun_tracking.c, demo3_moon.c, and demo4_multiple_sites.c.

Definition at line 426 of file skyio.c.

Macros

Functions

Detailed Description

Function Documentation

◆ skyio_degToDmsStr()

◆ skyio_hrsToHmsStr()

◆ skyio_sxStrToAng()

◆ skyio_radToDmsStr()

◆ skyio_radToHmsStr()

◆ skyio_printJ2kd()