Class Strings
- java.lang.Object
-
- uk.ac.starlink.ttools.func.Strings
-
public class Strings extends java.lang.Object
String manipulation and query functions.- Since:
- 2 Sep 2004
- Author:
- Mark Taylor (Starlink)
-
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static java.lang.String
concat(java.lang.Object... strings)
Concatenates multiple values into a string.static boolean
contains(java.lang.String whole, java.lang.String sub)
Determines whether a string contains a given substring.static double
desigToDec(java.lang.String designation)
Attempts to determine the ICRS Declination from an IAU-style designation such as "2MASS J04355524+1630331
" following the specifications in the document https://cdsweb.u-strasbg.fr/Dic/iau-spec.html.static double[]
desigToIcrs(java.lang.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 https://cdsweb.u-strasbg.fr/Dic/iau-spec.html.static double
desigToRa(java.lang.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 https://cdsweb.u-strasbg.fr/Dic/iau-spec.html.static boolean
endsWith(java.lang.String whole, java.lang.String end)
Determines whether a string ends with a certain substring.static boolean
equals(java.lang.String s1, java.lang.String s2)
Determines whether two strings are equal.static boolean
equalsIgnoreCase(java.lang.String s1, java.lang.String s2)
Determines whether two strings are equal apart from possible upper/lower case distinctions.static java.lang.String
join(java.lang.String separator, java.lang.Object... words)
Joins multiple values into a string, with a given separator between each pair.static int
length(java.lang.String str)
Returns the length of a string in characters.static boolean
matches(java.lang.String str, java.lang.String regex)
Tests whether a string matches a given regular expression.static java.lang.String
matchGroup(java.lang.String str, java.lang.String regex)
Returns the first grouped expression matched in a string defined by a regular expression.static java.lang.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 java.lang.String
replaceAll(java.lang.String str, java.lang.String regex, java.lang.String replacement)
Replaces all occurrences of a regular expression in a string with a different substring value.static java.lang.String
replaceFirst(java.lang.String str, java.lang.String regex, java.lang.String replacement)
Replaces the first occurrence of a regular expression in a string with a different substring value.static java.lang.String[]
split(java.lang.String words)
Splits a string into an array of space-separated words.static java.lang.String[]
split(java.lang.String words, java.lang.String regex)
Splits a string into an array of words separated by a given regular expression.static boolean
startsWith(java.lang.String whole, java.lang.String start)
Determines whether a string starts with a certain substring.static java.lang.String
substring(java.lang.String str, int startIndex)
Returns the last part of a given string.static java.lang.String
substring(java.lang.String str, int startIndex, int endIndex)
Returns a substring of a given string.static java.lang.String
toLowerCase(java.lang.String str)
Returns an lowercased version of a string.static java.lang.String
toUpperCase(java.lang.String str)
Returns an uppercased version of a string.static java.lang.String
trim(java.lang.String str)
Trims whitespace from both ends of a string.
-
-
-
Method Detail
-
concat
public static java.lang.String concat(java.lang.Object... strings)
Concatenates multiple values into a string. In some cases the same effect can be achieved by writings1+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 java.lang.String join(java.lang.String separator, java.lang.Object... words)
Joins multiple values into a string, with a given separator between each pair.- Parameters:
separator
- string to insert between adjacent wordswords
- 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(java.lang.String s1, java.lang.String s2)
Determines whether two strings are equal. Note you should use this function instead ofs1==s2
, which can (for technical reasons) return false even if the strings are the same.- Parameters:
s1
- first strings2
- second string- Returns:
- true if s1 and s2 are both blank, or have the same content
-
equalsIgnoreCase
public static boolean equalsIgnoreCase(java.lang.String s1, java.lang.String s2)
Determines whether two strings are equal apart from possible upper/lower case distinctions.- Parameters:
s1
- first strings2
- 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(java.lang.String whole, java.lang.String start)
Determines whether a string starts with a certain substring.- Parameters:
whole
- the string to teststart
- the sequence that may appear at the start ofwhole
- Returns:
- true if the first few characters of
whole
are the same asstart
- Examples:
startsWith("CYGNUS X-1", "CYG") = true
-
endsWith
public static boolean endsWith(java.lang.String whole, java.lang.String end)
Determines whether a string ends with a certain substring.- Parameters:
whole
- the string to testend
- the sequence that may appear at the end ofwhole
- Returns:
- true if the last few characters of
whole
are the same asend
- Examples:
endsWith("M32", "32") = true
-
contains
public static boolean contains(java.lang.String whole, java.lang.String sub)
Determines whether a string contains a given substring.- Parameters:
whole
- the string to testsub
- the sequence that may appear withinwhole
- Returns:
- true if the sequence
sub
appears withinwhole
- Examples:
contains("Vizier", "izi") = true
-
length
public static int length(java.lang.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 java.lang.String[] split(java.lang.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 java.lang.String[] split(java.lang.String words, java.lang.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 partsregex
- regular expression delimiting the different words in thewords
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(java.lang.String str, java.lang.String regex)
Tests whether a string matches a given regular expression.- Parameters:
str
- string to testregex
- regular expression string- Returns:
- true if
regex
matchesstr
anywhere - Examples:
matches("Hubble", "ub") = true
-
matchGroup
public static java.lang.String matchGroup(java.lang.String str, java.lang.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 againstregex
- regular expression containing a grouped section- Returns:
- contents of the matched group
(or null, if
regex
didn't matchstr
) - Examples:
matchGroup("NGC28948b","NGC([0-9]*)") = "28948"
-
replaceFirst
public static java.lang.String replaceFirst(java.lang.String str, java.lang.String regex, java.lang.String replacement)
Replaces the first occurrence of a regular expression in a string with a different substring value.- Parameters:
str
- string to manipulateregex
- regular expression to match instr
replacement
- replacement string- Returns:
- same as
str
, but with the first match (if any) ofregex
replaced byreplacement
- Examples:
replaceFirst("Messier 61", "Messier ", "M-") = "M-61"
-
replaceAll
public static java.lang.String replaceAll(java.lang.String str, java.lang.String regex, java.lang.String replacement)
Replaces all occurrences of a regular expression in a string with a different substring value.- Parameters:
str
- string to manipulateregex
- regular expression to match instr
replacement
- replacement string- Returns:
- same as
str
, but with all matches ofregex
replaced byreplacement
- Examples:
replaceAll("1-2--3---4","--*","x") = "1x2x3x4"
-
substring
public static java.lang.String substring(java.lang.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 stringstartIndex
- the beginning index, inclusive- Returns:
- last part of
str
, omitting the firststartIndex
characters - Examples:
substring("Galaxy", 2) = "laxy"
-
substring
public static java.lang.String substring(java.lang.String str, int startIndex, int endIndex)
Returns a substring of a given string. The substring begins with the character atstartIndex
and continues to the character at indexendIndex-1
Thus the length of the substring isendIndex-startIndex
.- Parameters:
str
- the input stringstartIndex
- the beginning index, inclusiveendIndex
- the end index, inclusive- Returns:
- substring of
str
- Examples:
substring("Galaxy", 2, 5) = "lax"
-
toUpperCase
public static java.lang.String toUpperCase(java.lang.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 java.lang.String toLowerCase(java.lang.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 java.lang.String trim(java.lang.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 java.lang.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 padndigit
- the number of digits in the resulting string- Returns:
- a string evaluating to the same as
value
with at leastndigit
characters - Examples:
padWithZeros(23,5) = "00023"
-
desigToRa
public static double desigToRa(java.lang.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 https://cdsweb.u-strasbg.fr/Dic/iau-spec.html.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(java.lang.String designation)
Attempts to determine the ICRS Declination from an IAU-style designation such as "2MASS J04355524+1630331
" following the specifications in the document https://cdsweb.u-strasbg.fr/Dic/iau-spec.html.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(java.lang.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 https://cdsweb.u-strasbg.fr/Dic/iau-spec.html.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
-
-