The following functions can be used anywhere that you can write an
algebraic expression in TOPCAT. They will typically be used for
defining new synthetic columns or algebraically-defined row subsets.
-
Strings
-
String manipulation and query functions.
-
concat( s1, s2 )
- Concatenates two strings.
In most cases the same effect can be achieved by
writing
s1+s2, but blank values can sometimes appear as
the string "null" if you do it like that.
-
concat( s1, s2, s3 )
- Concatenates three strings.
In most cases the same effect can be achieved by
writing
s1+s2+s3, but blank values can sometimes appear as
the string "null" if you do it like that.
-
concat( s1, s2, s3, s4 )
- Concatenates four strings.
In most cases the same effect can be achieved by
writing
s1+s2+s3+s4,
but blank values can sometimes appear as
the string "null" if you do it like that.
-
equals( s1, s2 )
- Determines whether two strings are equal.
Note you should use this function instead of
s1==s2,
which can (for technical reasons) return false even if the
strings are the same.
-
equalsIgnoreCase( s1, s2 )
- Determines whether two strings are equal apart from possible
upper/lower case distinctions.
-
startsWith( whole, start )
- Determines whether a string starts with a certain substring.
-
endsWith( whole, end )
- Determines whether a string ends with a certain substring.
-
contains( whole, sub )
- Determines whether a string contains a given substring.
-
length( str )
- Returns the length of a string in characters.
-
matches( str, regex )
- Tests whether a string matches a given regular expression.
-
matchGroup( str, regex )
- Returns the first grouped expression matched in a string defined
by a regular expression. A grouped expression is one enclosed
in parentheses.
-
replaceFirst( str, regex, replacement )
- Replaces the first occurrences of a regular expression in a string with
a different substring value.
-
replaceAll( str, regex, replacement )
- Replaces all occurrences of a regular expression in a string with
a different substring value.
-
substring( str, startIndex )
- Returns the last part of a given string.
The substring begins with the character at the specified
index and extends to the end of this string.
-
substring( str, startIndex, endIndex )
- Returns a substring of a given string.
The substring begins with the character at
startIndex
and continues to the character at index endIndex-1
Thus the length of the substring is endIndex-startIndex.
-
toUpperCase( str )
- Returns an uppercased version of a string.
-
toLowerCase( str )
- Returns an uppercased version of a string.
-
trim( str )
- Trims whitespace from either end of a string.
-
padWithZeros( value, ndigit )
- Takes an integer argument and returns a string representing the
same numeric value but padded with leading zeros to a specified
length.
-
Maths
-
Standard mathematical and trigonometric functions.
-
E
- Euler's number e, the base of natural logarithms.
-
PI
-
Pi, the ratio of the circumference of a circle to its diameter.
-
sin( theta )
- Sine of an angle.
-
cos( theta )
- Cosine of an angle.
-
tan( theta )
- Tangent of an angle.
-
asin( x )
- Arc sine of an angle.
The result is in the range of -pi/2 through
pi/2.
-
acos( x )
- Arc cosine of an angle.
The result is in the range of 0.0 through pi.
-
atan( x )
- Arc tangent of an angle.
The result is in the range of -pi/2 through pi/2.
-
exp( x )
- Euler's number e raised to a power.
-
log10( x )
- Logarithm to base 10.
-
ln( x )
- Natural logarithm.
-
sqrt( x )
- Square root.
The result is correctly rounded and positive.
-
atan2( y, x )
- Converts rectangular coordinates (
x,y)
to polar (r,theta).
This method computes the phase
theta by computing an arc tangent
of y/x in the range of -pi to pi.
-
pow( a, b )
- Exponentiation.
The result is the value of the first argument raised to
the power of the second argument.
-
Coords
-
Functions for angle transformations and manipulations.
In particular, methods for translating between radians and HH:MM:SS.S
or DDD:MM:SS.S type sexagesimal representations are provided.
-
DEGREE
- The size of one degree in radians.
-
ARC_MINUTE
- The size of one arcminute in radians.
-
ARC_SECOND
- The size of one arcsecond in radians.
-
radiansToDms( rad )
- Converts an angle in radians to a formatted degrees:minutes:seconds
string. No fractional part of the seconds field is given.
-
radiansToDms( rad, secFig )
- Converts an angle in radians to a formatted degrees:minutes:seconds
string with a given number of decimal places in the seconds field.
-
radiansToHms( rad )
- Converts an angle in radians to a formatted hours:minutes:seconds
string. No fractional part of the seconds field is given.
-
radiansToHms( rad, secFig )
- Converts an angle in radians to a formatted hours:minutes:seconds
string with a given number of decimal places in the seconds field.
-
dmsToRadians( dms )
- Converts a formatted degrees:minutes:seconds string to an angle
in radians. Delimiters may be colon, space, characters
dm[s], or some others.
Additional spaces and leading +/- are permitted.
-
hmsToRadians( hms )
- Converts a formatted hours:minutes:seconds string to an angle
in radians. Delimiters may be colon, space, characters
hm[s], or some others.
Additional spaces and leading +/- are permitted.
-
dmsToRadians( deg, min, sec )
- Converts degrees, minutes, seconds to an angle in radians.
In conversions of this type, one has to be careful to get the
sign right in converting angles which are between 0 and -1 degrees.
This routine uses the sign bit of the deg argument,
taking care to distinguish between +0 and -0 (their internal
representations are different for floating point values).
It is illegal for the min or sec arguments
to be negative.
-
hmsToRadians( hour, min, sec )
- Converts hours, minutes, seconds to an angle in radians.
In conversions of this type, one has to be careful to get the
sign right in converting angles which are between 0 and -1 hours.
This routine uses the sign bit of the hour argument,
taking care to distinguish between +0 and -0 (their internal
representations are different for floating point values).
-
skyDistance( ra1, dec1, ra2, dec2 )
- Calculates the separation (distance around a great circle) of
two points on the sky.
-
hoursToRadians( hours )
- Converts hours to radians.
-
degreesToRadians( deg )
- Converts degrees to radians.
-
radiansToDegrees( rad )
- Converts radians to degrees.
-
raFK4toFK5( raFK4, decFK4 )
- Converts a B1950.0 FK4 position to J2000.0 FK5 at an epoch of B1950.0
yielding Right Ascension.
This assumes zero proper motion in the FK5 frame.
-
decFK4toFK5( raFK4, decFK4 )
- Converts a B1950.0 FK4 position to J2000.0 FK5 at an epoch of B1950.0
yielding Declination
This assumes zero proper motion in the FK5 frame.
-
raFK5toFK4( raFK5, decFK5 )
- Converts a J2000.0 FK5 position to B1950.0 FK4 at an epoch of B1950.0
yielding Declination.
This assumes zero proper motion, parallax and radial velocity in
the FK5 frame.
-
decFK5toFK4( raFK5, decFK5 )
- Converts a J2000.0 FK5 position to B1950.0 FK4 at an epoch of B1950.0
yielding Declination.
This assumes zero proper motion, parallax and radial velocity in
the FK5 frame.
-
raFK4toFK5( raFK4, decFK4, bepoch )
- Converts a B1950.0 FK4 position to J2000.0 FK5 yielding Right Ascension.
This assumes zero proper motion in the FK5 frame.
The
bepoch parameter is the epoch at which the position in
the FK4 frame was determined.
-
decFK4toFK5( raFK4, decFK4, bepoch )
- Converts a B1950.0 FK4 position to J2000.0 FK5 yielding Declination.
This assumes zero proper motion in the FK5 frame.
The
bepoch parameter is the epoch at which the position in
the FK4 frame was determined.
-
raFK5toFK4( raFK5, decFK5, bepoch )
- Converts a J2000.0 FK5 position to B1950.0 FK4 yielding Declination.
This assumes zero proper motion, parallax and radial velocity in
the FK5 frame.
-
decFK5toFK4( raFK5, decFK5, bepoch )
- Converts a J2000.0 FK5 position to B1950.0 FK4 yielding Declination.
This assumes zero proper motion, parallax and radial velocity in
the FK5 frame.
-
Conversions
-
Functions for coverting between strings and numeric values.
-
toString( value )
- Turns a numeric value into a string.
-
parseByte( str )
- Attempts to interpret a string as a byte (8-bit signed integer) value.
If the input string can't be interpreted in this way, a blank
value will result.
-
parseShort( str )
- Attempts to interpret a string as a short (16-bit signed integer) value.
If the input string can't be interpreted in this way, a blank
value will result.
-
parseInt( str )
- Attempts to interpret a string as an int (32-bit signed integer) value.
If the input string can't be interpreted in this way, a blank
value will result.
-
parseLong( str )
- Attempts to interpret a string as a long (64-bit signed integer) value.
If the input string can't be interpreted in this way, a blank
value will result.
-
parseFloat( str )
- Attempts to interpret a string as a float (32-bit floating point) value.
If the input string can't be interpreted in this way, a blank
value will result.
-
parseDouble( str )
- Attempts to interpret a string as a double (64-bit signed integer) value.
If the input string can't be interpreted in this way, a blank
value will result.
-
toByte( value )
- Attempts to convert the numeric argument to a
byte (8-bit signed integer) result.
If it is out of range, a blank value will result.
-
toShort( value )
- Attempts to convert the numeric argument to a
short (16-bit signed integer) result.
If it is out of range, a blank value will result.
-
toInteger( value )
- Attempts to convert the numeric argument to an
int (32-bit signed integer) result.
If it is out of range, a blank value will result.
-
toLong( value )
- Attempts to convert the numeric argument to a
long (64-bit signed integer) result.
If it is out of range, a blank value will result.
-
toFloat( value )
- Attempts to convert the numeric argument to a
float (32-bit floating point) result.
If it is out of range, a blank value will result.
-
toDouble( value )
- Converts the numeric argument to a
double (64-bit signed integer) result.
-
Arithmetic
-
Standard arithmetic functions including things like rounding,
sign manipulation, and maximum/minimum functions.
-
roundUp( x )
- Rounds a value up to an integer value.
Formally, returns the smallest (closest to negative infinity)
integer value that is not less than the argument.
-
roundDown( x )
- Rounds a value down to an integer value.
Formally, returns the largest (closest to positive infinity)
integer value that is not greater than the argument.
-
round( x )
- Rounds a value to the nearest integer.
Formally,
returns the integer that is closest in value
to the argument. If two integers are
equally close, the result is the even one.
-
abs( x )
- Returns the absolute value of an
int value.
If the argument is not negative, the argument is returned.
If the argument is negative, the negation of the argument is returned.
-
abs( x )
- Returns the absolute value of a
double value.
If the argument is not negative, the argument is returned.
If the argument is negative, the negation of the argument is returned.
-
max( a, b )
- Returns the greater of two
int values.
If the arguments have the same value, the result is that same value.
-
max( a, b )
- Returns the greater of two
double values.
If the arguments have the same value, the result is that same
value. If either value is blank, then the result is blank.
-
min( a, b )
- Returns the smaller of two
int values.
If the arguments have the same value, the result is that same value.
-
min( a, b )
- Returns the smaller of two
double values.
If the arguments have the same value, the result is that same value.
If either value is blank, then the result is blank.
More detail on these functions is available from within TOPCAT in the
Available Functions window.