Class 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 http://cds.u-strasbg.fr/vizier/Dic/iau-spec.htx.
      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 http://cds.u-strasbg.fr/vizier/Dic/iau-spec.htx.
      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 http://cds.u-strasbg.fr/vizier/Dic/iau-spec.htx.
      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.
      static java.lang.String urlDecode​(java.lang.String txt)
      Reverses the quoting performed by urlEncode.
      static java.lang.String urlEncode​(java.lang.String txt)
      Performs necessary quoting of a string for it to be included safely in the data part of a URL.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • 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 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 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 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​(java.lang.String s1,
                                     java.lang.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​(java.lang.String s1,
                                               java.lang.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​(java.lang.String whole,
                                         java.lang.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​(java.lang.String whole,
                                       java.lang.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​(java.lang.String whole,
                                       java.lang.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​(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 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​(java.lang.String str,
                                      java.lang.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 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 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 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 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 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 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 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 string
        startIndex - the beginning index, inclusive
        Returns:
        last part of str, omitting the first startIndex 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 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 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 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"
      • urlEncode

        public static java.lang.String urlEncode​(java.lang.String txt)
        Performs necessary quoting of a string for it to be included safely in the data part of a URL. Alphanumeric characters and the characters underscore ("_"), minus sign ("-"), period (".") and tilde ("~") are passed through unchanged, and any other 7-bit ASCII character is represented by a percent sign ("%") followed by its 2-digit hexadecimal code. Characters with values of 128 or greater are simply dropped.
        Parameters:
        txt - input (unencoded) string
        Returns:
        output (encoded) string
        See Also:
        RFC 3986
        Examples:
        urlEncode("RR Lyr") = "RR%20Lyr"
      • urlDecode

        public static java.lang.String urlDecode​(java.lang.String txt)
        Reverses the quoting performed by urlEncode. Percent-encoded sequences (%xx) are replaced by the ASCII character with the hexadecimal code xx.
        Parameters:
        txt - input (encoded) string
        Returns:
        output (unencoded) string
        See Also:
        RFC 3986
        Examples:
        urlDecode("RR%20Lyr") = "RR Lyr"
      • 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 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​(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 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​(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 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