API Reference

deg2dms(angle)

Convert degrees to (degrees, arcminutes, arcseconds) tuple.

If angle is Missing, returns missing.

deg2ha(angle)

Convert degrees to hour angles.

If angle is Missing, returns missing.

deg2hms(angle)

Convert degrees to (hours, minutes, seconds) tuple.

If angle is Missing, returns missing.

dms2deg(degrees, arcmin, arcsec)
dms2deg(parts)
dms2deg(input::AbstractString)

Convert (degrees, arcminutes, arcseconds) tuple to degrees. If a string is given, will parse with parse_dms first. If an angle is input will treat as a no-op.

If any input is Missing, returns missing.

dms2ha(degrees, arcmin, arcsec)
dms2ha(parts)
dms2ha(input::AbstractString)

Convert (degrees, arcminutes, arcseconds) tuple to hour angles. If a string is given, will parse with parse_dms first. If an angle is input will treat as a no-op.

If any input is Missing, returns missing.

dms2rad(degrees, arcmin, arcsec)
dms2rad(parts)
dms2rad(input::AbstractString)

Convert (degrees, arcminutes, arcseconds) tuple to radians. If a string is given, will parse with parse_dms first. If an angle is input will treat as a no-op.

If any input is Missing, returns missing.

format_angle(parts; delim = ':', digits = 2, pad = true, alwayssign = false)
format_angle(parts...; kwargs...)

Format the parts of an angle into a delimited string. The parts are typically the (whole, minutes, seconds) produced by the deg2dms, deg2hms, rad2dms, rad2hms, ha2dms, and ha2hms methods, and may be passed either as a single tuple (or vector) or as separate positional arguments.

Any number of parts is supported: every part except the last is formatted as a whole number, and the last part keeps its fractional digits. This allows extended sub-arcsecond splits like (degrees, arcminutes, arcseconds, mas, μas) as well as partial splits like (minutes, seconds). The sign of the angle is taken from the first part, matching the convention of the conversion methods above, which carry the sign only on their first part. For more control over formatting, consider using Printf or a package like Format.jl.

If any part is missing, returns missing.

Keyword arguments

• delim: The delimiter(s) placed between the parts. A single Char/String (default ':') is inserted between each part, e.g. "45:00:00.00". A vector or tuple with one delimiter per part is instead appended after each respective part, e.g., delim = ["h", "m", "s"] gives "05h43m46.48s".
• digits: The number of digits to round the last part to (default 2). Pass 0 to display it as a whole number, or "all" to keep full precision without rounding.
• pad: If true (default), zero-pad the whole-number portion of each part to at least two characters and the fractional digits of the last part to digits, e.g. "03:00:00.00".
• alwayssign: If true, prefix non-negative angles with '+' (default false). Negative angles are always prefixed with '-'.

Examples

julia> ang = 45.0; # degrees

julia> format_angle(deg2dms(ang))
"45:00:00.00"

julia> format_angle(deg2hms(ang))
"03:00:00.00"

julia> format_angle(rad2hms(1.5), delim=["h", "m", "s"])
"05h43m46.48s"

julia> format_angle(rad2hms(1.5), delim=["h", "m", "s"]; digits=5)
"05h43m46.48062s"

julia> format_angle(rad2hms(1.5), delim=["h", "m", "s"]; digits="all")
"05h43m46.48062470963538s"

julia> format_angle(deg2dms(45.0); pad=false)
"45:0:0.0"

julia> format_angle(deg2dms(45.0); alwayssign=true)
"+45:00:00.00"

julia> format_angle(deg2dms(-45.0); alwayssign=true)
"-45:00:00.00"

julia> format_angle((23, 33.6), delim=["ᵐ", "ˢ"]) # partial split
"23ᵐ33.60ˢ"

julia> format_angle((58, 48, 12.0), delim=["°", "′", "″"]; digits=0)
"58°48′12″"

See also

deg2dms, deg2hms, rad2dms, rad2hms, ha2dms, ha2hms

ha2deg(angle)

Convert hour angles to degrees.

If angle is Missing, returns missing.

ha2dms(angle)

Convert hour angles to (degrees, arcminutes, arcseconds) tuple.

If angle is Missing, returns missing.

ha2hms(angle)

Convert hour angles to (hours, minutes, seconds) tuple.

If angle is Missing, returns missing.

ha2rad(angle)

Convert hour angles to radians.

If angle is Missing, returns missing.

hms2deg(hours, mins, secs)
hms2deg(parts)
hms2deg(input::AbstractString)

Convert (hours, minutes, seconds) tuple to degrees. If a string is given, will parse with parse_hms first. If an angle is input will treat as a no-op.

If any input is Missing, returns missing.

hms2ha(hours, mins, secs)
hms2ha(parts)
hms2ha(input::AbstractString)

Convert (hours, minutes, seconds) tuple to hour angles. If a string is given, will parse with parse_hms first. If an angle is input will treat as a no-op.

If any input is Missing, returns missing.

hms2rad(hours, mins, secs)
hms2rad(parts)
hms2rad(input::AbstractString)

Convert (hours, minutes, seconds) tuple to radians. If a string is given, will parse with parse_hms first. If an angle is input will treat as a no-op.

If any input is Missing, returns missing.

parse_dms(input)

Parse a string in "deg:arcmin:arcsec" format to the tuple (degrees, arcminutes, arcseconds). The following delimiters all work and may be mixed together (the final delimiter is optional):

"[+-]xx[°d: ]xx['′m: ]xx[\"″s][NESW]"

A value carrying an arcminute (', ′, m) or arcsecond (", ″, s) unit is placed in that component rather than being read positionally, so "2m3s" parses as two arcminutes plus three arcseconds. Values separated by ambiguous delimiters (: or whitespace) fill the components positionally. Components given out of order (e.g. "3s2m") raise an ArgumentError.

If the direction is provided, "S" and "W" are considered negative (so "-1:0:0S" is 1 degree North).

If input is Missing, returns missing.

Examples

julia> parse_dms("12:17:25.3")
(12.0, 17.0, 25.3)

julia> parse_dms("1'")
(0.0, 1.0, 0.0)

julia> parse_dms("2m3s")
(0.0, 2.0, 3.0)

parse_hms(input)

Parse a string in "hour:min:sec" format to the tuple (hours, minutes, seconds). The following delimiters all work and may be mixed together (the final delimiter is optional):

"[+-]xx[h ]xx['′m: ]xx[\"″s][EW]"

As with parse_dms, a value carrying a minute (', ′, m) or second (", ″, s) unit is placed in that component rather than positionally, values separated by ambiguous delimiters fill positionally, and components given out of order raise an ArgumentError.

If the direction is provided, "S" and "W" are considered negative (so "-1:0:0W" is 1 hour East).

If input is Missing, returns missing.

rad2dms(angle)

Convert radians to (degrees, arcminutes, arcseconds) tuple.

If angle is Missing, returns missing.

rad2ha(angle)

Convert radians to hour angles.

If angle is Missing, returns missing.

rad2hms(angle)

Convert radians to (hours, minutes, seconds) tuple.

If angle is Missing, returns missing.

@dms_str

Parse a string in "deg:arcmin:arcsec" format directly to an angle. By default, it will be parsed as radians, but the angle can be chosen by adding a flag to the end of the string.

• dms"..."rad –> radians (default)
• dms"..."deg –> degrees
• dms"..."ha –> hour angles

Examples

julia> dms"12:17:25.3"
0.21450726764795752

julia> dms"12:17:25.3"rad # default
0.21450726764795752

julia> dms"12:17:25.3"deg
12.29036111111111

julia> dms"12:17:25.3"ha
0.8193574074074074

See also

parse_dms

@hms_str

Parse a string in "ha:min:sec" format directly to an angle. By default, it will be parsed as radians, but the angle can be chosen by adding a flag to the end of the string.

• hms"..."rad –> radians (default)
• hms"..."deg –> degrees
• hms"..."ha –> hour angles

Examples

julia> hms"12:17:25.3"
3.2176090147193626

julia> hms"12:17:25.3"rad # default
3.2176090147193626

julia> hms"12:17:25.3"deg
184.35541666666666

julia> hms"12:17:25.3"ha
12.29036111111111

See also

parse_hms