# 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

Modifier and Type
Method
Description
`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 https://cdsweb.u-strasbg.fr/Dic/iau-spec.html.
`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 https://cdsweb.u-strasbg.fr/Dic/iau-spec.html.
`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 https://cdsweb.u-strasbg.fr/Dic/iau-spec.html.
`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 Object

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

## Method Details

### 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 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(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(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