uk.ac.starlink.ttools.func
Class Strings

java.lang.Object
  uk.ac.starlink.ttools.func.Strings

public class Strings
extends Object

String manipulation and query functions.

Since:

2 Sep 2004

Author:

Mark Taylor (Starlink)

Method Summary

static String	concat(Object... strings) Concatenates multiple values into a string.
static boolean	contains(String whole, String sub) Determines whether a string contains a given substring.
static double	desigToDec(String designation) Attempts to determine the ICRS Declination from an IAU-style designation such as "2MASS J04355524+1630331" following the specifications in the document http://cds.u-strasbg.fr/vizier/Dic/iau-spec.htx.
static double[]	desigToIcrs(String designation) Attempts to decode an IAU-style designation such as "2MASS J04355524+1630331" to determine its sky position, following the specifications in the document http://cds.u-strasbg.fr/vizier/Dic/iau-spec.htx.
static double	desigToRa(String designation) Attempts to determine the ICRS Right Ascension from an IAU-style designation such as "2MASS J04355524+1630331" following the specifications in the document http://cds.u-strasbg.fr/vizier/Dic/iau-spec.htx.
static boolean	endsWith(String whole, String end) Determines whether a string ends with a certain substring.
static boolean	equals(String s1, String s2) Determines whether two strings are equal.
static boolean	equalsIgnoreCase(String s1, String s2) Determines whether two strings are equal apart from possible upper/lower case distinctions.
static String	join(String separator, Object... words) Joins multiple values into a string, with a given separator between each pair.
static int	length(String str) Returns the length of a string in characters.
static boolean	matches(String str, String regex) Tests whether a string matches a given regular expression.
static String	matchGroup(String str, String regex) Returns the first grouped expression matched in a string defined by a regular expression.
static String	padWithZeros(long value, int ndigit) Takes an integer argument and returns a string representing the same numeric value but padded with leading zeros to a specified length.
static String	replaceAll(String str, String regex, String replacement) Replaces all occurrences of a regular expression in a string with a different substring value.
static String	replaceFirst(String str, String regex, String replacement) Replaces the first occurrence of a regular expression in a string with a different substring value.
static String[]	split(String words) Splits a string into an array of space-separated words.
static String[]	split(String words, String regex) Splits a string into an array of words separated by a given regular expression.
static boolean	startsWith(String whole, String start) Determines whether a string starts with a certain substring.
static String	substring(String str, int startIndex) Returns the last part of a given string.
static String	substring(String str, int startIndex, int endIndex) Returns a substring of a given string.
static String	toLowerCase(String str) Returns an lowercased version of a string.
static String	toUpperCase(String str) Returns an uppercased version of a string.
static String	trim(String str) Trims whitespace from both ends of a string.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

concat

public static String concat(Object... strings)

Concatenates multiple values into a string. In some cases the same effect can be achieved by writing s1+s2+..., but this method makes sure that values are converted to strings, with the blank value invisible.

Parameters:

strings - one or more strings

Returns:

concatenation of input strings, without separators

Examples:

concat("blue", "moon") = "bluemoon", concat("1", 2, 3, "4") = "1234", concat("Astro", null, "Physics") = "AstroPhysics"

join

public static String join(String separator,
                          Object... words)

Joins multiple values into a string, with a given separator between each pair.

Parameters:

separator - string to insert between adjacent words

words - one or more values to join

Returns:

input values joined together with separator

Examples:

join("<->", "alpha", "beta", "gamma") = "alpha<->beta<->gamma", join(" ", 1, "brown", "mouse") = "1 brown mouse"

equals

public static boolean equals(String s1,
                             String 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.

Parameters:

s1 - first string

s2 - second string

Returns:

true if s1 and s2 are both blank, or have the same content

equalsIgnoreCase

public static boolean equalsIgnoreCase(String s1,
                                       String s2)

Determines whether two strings are equal apart from possible upper/lower case distinctions.

Parameters:

s1 - first string

s2 - second string

Returns:

true if s1 and s2 are both blank, or have the same content apart from case folding

Examples:

equalsIgnoreCase("Cygnus", "CYGNUS") = true, equalsIgnoreCase("Cygnus", "Andromeda") = false

startsWith

public static boolean startsWith(String whole,
                                 String start)

Determines whether a string starts with a certain substring.

Parameters:

whole - the string to test

start - the sequence that may appear at the start of whole

Returns:

true if the first few characters of whole are the same as start

Examples:

startsWith("CYGNUS X-1", "CYG") = true

endsWith

public static boolean endsWith(String whole,
                               String end)

Determines whether a string ends with a certain substring.

Parameters:

whole - the string to test

end - the sequence that may appear at the end of whole

Returns:

true if the last few characters of whole are the same as end

Examples:

endsWith("M32", "32") = true

contains

public static boolean contains(String whole,
                               String sub)

Determines whether a string contains a given substring.

Parameters:

whole - the string to test

sub - the sequence that may appear within whole

Returns:

true if the sequence sub appears within whole

Examples:

contains("Vizier", "izi") = true

length

public static int length(String str)

Returns the length of a string in characters.

Parameters:

str - string

Returns:

number of characters in str

Examples:

length("M34") = 3

split

public static String[] split(String words)

Splits a string into an array of space-separated words. One or more spaces separates each word from the next. Leading and trailing spaces are ignored.

The result is an array of strings, and if you want to use the individual elements you need to use square-bracket indexing, with [0] representing the first object

Parameters:

words - string with embedded spaces delimiting the words

Returns:

array of the separate words; you can extract the individual words from the result using square bracket indexing

Examples:

split("211:54:01 +29:33:41") gives a 2-element array, first element is "211:54:01" and second element is "+29:33:41"., split(" cat dog cow ")[1] = "dog"

split

public static String[] split(String words,
                             String regex)

Splits a string into an array of words separated by a given regular expression.

The result is an array of strings, and if you want to use the individual elements you need to use square-bracket indexing, with [0] representing the first object

Parameters:

words - string with multiple parts

regex - regular expression delimiting the different words in the words parameter

Returns:

array of the separate words; you can extract the individual words from the result using square bracket indexing

Examples:

split("cat, dog, cow", ", *") gives a 3-element string array., split("23.0, 45.92", ", ")[0] = "23.0", parseDouble(split("23.0, 45.92", ", ")[0]) = 23

matches

public static boolean matches(String str,
                              String regex)

Tests whether a string matches a given regular expression.

Parameters:

str - string to test

regex - regular expression string

Returns:

true if regex matches str anywhere

Examples:

matches("Hubble", "ub") = true

matchGroup

public static String matchGroup(String str,
                                String regex)

Returns the first grouped expression matched in a string defined by a regular expression. A grouped expression is one enclosed in parentheses.

Parameters:

str - string to match against

regex - regular expression containing a grouped section

Returns:

contents of the matched group (or null, if regex didn't match str)

Examples:

matchGroup("NGC28948b","NGC([0-9]*)") = "28948"

replaceFirst

public static String replaceFirst(String str,
                                  String regex,
                                  String replacement)

Replaces the first occurrence of a regular expression in a string with a different substring value.

Parameters:

str - string to manipulate

regex - regular expression to match in str

replacement - replacement string

Returns:

same as str, but with the first match (if any) of regex replaced by replacement

Examples:

replaceFirst("Messier 61", "Messier ", "M-") = "M-61"

replaceAll

public static String replaceAll(String str,
                                String regex,
                                String replacement)

Replaces all occurrences of a regular expression in a string with a different substring value.

Parameters:

str - string to manipulate

regex - regular expression to match in str

replacement - replacement string

Returns:

same as str, but with all matches of regex replaced by replacement

Examples:

replaceAll("1-2--3---4","--*","x") = "1x2x3x4"

substring

public static String substring(String str,
                               int 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.

Parameters:

str - the input string

startIndex - the beginning index, inclusive

Returns:

last part of str, omitting the first startIndex characters

Examples:

substring("Galaxy", 2) = "laxy"

substring

public static String substring(String str,
                               int startIndex,
                               int 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.

Parameters:

str - the input string

startIndex - the beginning index, inclusive

endIndex - the end index, inclusive

Returns:

substring of str

Examples:

substring("Galaxy", 2, 5) = "lax"

toUpperCase

public static String toUpperCase(String str)

Returns an uppercased version of a string.

Parameters:

str - input string

Returns:

uppercased version of str

Examples:

toUpperCase("Universe") = "UNIVERSE"

toLowerCase

public static String toLowerCase(String str)

Returns an lowercased version of a string.

Parameters:

str - input string

Returns:

lowercased version of str

Examples:

toLowerCase("Universe") = "universe"

trim

public static String trim(String str)

Trims whitespace from both ends of a string.

Parameters:

str - input string

Returns:

str with any spaces trimmed from start and finish

Examples:

trim(" some text ") = "some text", trim("some text") = "some text"

padWithZeros

public static String padWithZeros(long value,
                                  int ndigit)

Takes an integer argument and returns a string representing the same numeric value but padded with leading zeros to a specified length.

Parameters:

value - numeric value to pad

ndigit - the number of digits in the resulting string

Returns:

a string evaluating to the same as value with at least ndigit characters

Examples:

padWithZeros(23,5) = "00023"

desigToRa

public static double desigToRa(String designation)

Attempts to determine the ICRS Right Ascension from an IAU-style designation such as "2MASS J04355524+1630331" following the specifications in the document http://cds.u-strasbg.fr/vizier/Dic/iau-spec.htx.

Note: this function should be used with considerable care. Such designators are intended for object identification and not for communicating sky positions, so that the resulting positions are likely to lack precision, and may be inaccurate. If positional information is available from other sources, it should almost certainly be used instead. But if there's no other choice, this may be used as a fallback.

Note also that a designator with no coordsystem-specific flag character (a leading "J", "B" or "G") is considered to be B1950, not J2000.

Parameters:

designation - designation string in IAU format

Returns:

ICRS right ascension in degreees, or blank if no position can be decoded

Examples:

desigToRa("2MASS J04355524+1630331") = 60.98016, desigToRa("PSR J120000.0+450000.0") = 180, desigToDec("PSR B120000.0+450000.0") = 180.639096, desigToRa("PN G001.2-00.3") = 267.403, desigToRa("NGC 4993") = NaN

desigToDec

public static double desigToDec(String designation)

Attempts to determine the ICRS Declination from an IAU-style designation such as "2MASS J04355524+1630331" following the specifications in the document http://cds.u-strasbg.fr/vizier/Dic/iau-spec.htx.

Note: this function should be used with considerable care. Such designators are intended for object identification and not for communicating sky positions, so that the resulting positions are likely to lack precision, and may be inaccurate. If positional information is available from other sources, it should almost certainly be used instead. But if there's no other choice, this may be used as a fallback.

Note also that a designator with no coordsystem-specific flag character (a leading "J", "B" or "G") is considered to be B1950, not J2000.

Parameters:

designation - designation string in IAU format

Returns:

ICRS declination in degrees, or blank if no position can be decoded

Examples:

desigToDec("2MASS J04355524+1630331") = 16.50919, desigToDec("PSR J120000.0+450000.0") = 45, desigToDec("PSR B120000.0+450000.0") = 44.72167, desigToDec("PN G001.2-00.3") = -28.06457, desigToDec("NGC 4993") = NaN

desigToIcrs

public static double[] desigToIcrs(String designation)

Attempts to decode an IAU-style designation such as "2MASS J04355524+1630331" to determine its sky position, following the specifications in the document http://cds.u-strasbg.fr/vizier/Dic/iau-spec.htx.

Obviously, this only works where the sequence part of the designation takes one of the family of coordinate-based forms.

Note: this function should be used with considerable care. Such designators are intended for object identification and not for communicating sky positions, so that the resulting positions are likely to lack precision, and may be inaccurate. If positional information is available from other sources, it should almost certainly be used instead. But if there's no other choice, this may be used as a fallback.

Note also that a designator with no coordsystem-specific flag character (a leading "J", "B" or "G") is considered to be B1950, not J2000.

Parameters:

designation - designation string in IAU format

Returns:

2-element array giving ICRS (RA,Dec) in degrees, or null if no position can be decoded