Next Previous Up Contents
Next: Tilings
Up: Functions
Previous: Sky

#### 10.7.19 Strings

String manipulation and query functions.

`concat( 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` (Object, one or more): one or more strings
  - Return value
    - (String): concatenation of input strings, without separators
  - Examples:
    - `concat("blue", "moon") = "bluemoon"`
    - `concat("1", 2, 3, "4") = "1234"`
    - `concat("Astro", null, "Physics") = "AstroPhysics"`
`join( separator, words, ... )`
  Joins multiple values into a string, with a given separator between each pair.

  - Parameters:
    - `separator` (String): string to insert between adjacent words
    - `words` (Object, one or more): one or more values to join
  - Return value
    - (String): input values joined together with `separator`
  - Examples:
    - `join("<->", "alpha", "beta", "gamma") = "alpha<->beta<->gamma"`
    - `join(" ", 1, "brown", "mouse") = "1 brown mouse"`
`equals( s1, s2 )`
  Determines whether two strings are equal.

  This will usually give the same result as `s1==s2`, but it is arguably safer and may behave better when comparing different kinds of blank strings.

  - Parameters:
    - `s1` (String): first string
    - `s2` (String): second string
  - Return value
    - (boolean): true if s1 and s2 are both blank, or have the same content
`equalsIgnoreCase( s1, s2 )`
  Determines whether two strings are equal apart from possible upper/lower case distinctions.

  - Parameters:
    - `s1` (String): first string
    - `s2` (String): second string
  - Return value
    - (boolean): 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( whole, start )`
  Determines whether a string starts with a certain substring.

  - Parameters:
    - `whole` (String): the string to test
    - `start` (String): the sequence that may appear at the start of `whole`
  - Return value
    - (boolean): true if the first few characters of `whole` are the same as `start`
  - Example:
    - `startsWith("CYGNUS X-1", "CYG") = true`
`endsWith( whole, end )`
  Determines whether a string ends with a certain substring.

  - Parameters:
    - `whole` (String): the string to test
    - `end` (String): the sequence that may appear at the end of `whole`
  - Return value
    - (boolean): true if the last few characters of `whole` are the same as `end`
  - Example:
    - `endsWith("M32", "32") = true`
`contains( whole, sub )`
  Determines whether a string contains a given substring.

  - Parameters:
    - `whole` (String): the string to test
    - `sub` (String): the sequence that may appear within `whole`
  - Return value
    - (boolean): true if the sequence `sub` appears within `whole`
  - Example:
    - `contains("Vizier", "izi") = true`
`length( str )`
  Returns the length of a string in characters.

  - Parameters:
    - `str` (String): string
  - Return value
    - (integer): number of characters in `str`
  - Example:
    - `length("M34") = 3`
`split( 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): string with embedded spaces delimiting the words
  - Return value
    - (array of String): 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( words, 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): string with multiple parts
    - `regex` (String): regular expression delimiting the different words in the `words` parameter
  - Return value
    - (array of String): 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( str, regex )`
  Tests whether a string matches a given regular expression.

  - Parameters:
    - `str` (String): string to test
    - `regex` (String): regular expression string
  - Return value
    - (boolean): true if `regex` matches `str` anywhere
  - Example:
    - `matches("Hubble", "ub") = true`
`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.

  - Parameters:
    - `str` (String): string to match against
    - `regex` (String): regular expression containing a grouped section
  - Return value
    - (String): contents of the matched group (or null, if `regex` didn't match `str`)
  - Example:
    - `matchGroup("NGC28948b","NGC([0-9]*)") = "28948"`
`replaceFirst( str, regex, replacement )`
  Replaces the first occurrence of a regular expression in a string with a different substring value.

  - Parameters:
    - `str` (String): string to manipulate
    - `regex` (String): regular expression to match in `str`
    - `replacement` (String): replacement string
  - Return value
    - (String): same as `str`, but with the first match (if any) of `regex` replaced by `replacement`
  - Example:
    - `replaceFirst("Messier 61", "Messier ", "M-") = "M-61"`
`replaceAll( str, regex, replacement )`
  Replaces all occurrences of a regular expression in a string with a different substring value.

  - Parameters:
    - `str` (String): string to manipulate
    - `regex` (String): regular expression to match in `str`
    - `replacement` (String): replacement string
  - Return value
    - (String): same as `str`, but with all matches of `regex` replaced by `replacement`
  - Example:
    - `replaceAll("1-2--3---4","--*","x") = "1x2x3x4"`
`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.

  - Parameters:
    - `str` (String): the input string
    - `startIndex` (integer): the beginning index, inclusive
  - Return value
    - (String): last part of `str`, omitting the first `startIndex` characters
  - Example:
    - `substring("Galaxy", 2) = "laxy"`
`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`.

  - Parameters:
    - `str` (String): the input string
    - `startIndex` (integer): the beginning index, inclusive
    - `endIndex` (integer): the end index, inclusive
  - Return value
    - (String): substring of `str`
  - Example:
    - `substring("Galaxy", 2, 5) = "lax"`
`toUpperCase( str )`
  Returns an uppercased version of a string.

  - Parameters:
    - `str` (String): input string
  - Return value
    - (String): uppercased version of `str`
  - Example:
    - `toUpperCase("Universe") = "UNIVERSE"`
`toLowerCase( str )`
  Returns an lowercased version of a string.

  - Parameters:
    - `str` (String): input string
  - Return value
    - (String): lowercased version of `str`
  - Example:
    - `toLowerCase("Universe") = "universe"`
`trim( str )`
  Trims whitespace from both ends of a string.

  - Parameters:
    - `str` (String): input string
  - Return value
    - (String): str with any spaces trimmed from start and finish
  - Examples:
    - `trim(" some text ") = "some text"`
    - `trim("some text") = "some text"`
`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.

  - Parameters:
    - `value` (long integer): numeric value to pad
    - `ndigit` (integer): the number of digits in the resulting string
  - Return value
    - (String): a string evaluating to the same as `value` with at least `ndigit` characters
  - Example:
    - `padWithZeros(23,5) = "00023"`
`desigToRa( 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://cds.unistra.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` (String): designation string in IAU format
  - Return value
    - (floating point): 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( designation )`
  Attempts to determine the ICRS Declination from an IAU-style designation such as "`2MASS J04355524+1630331`" following the specifications in the document https://cds.unistra.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` (String): designation string in IAU format
  - Return value
    - (floating point): 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( 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://cds.unistra.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` (String): designation string in IAU format
  - Return value
    - (array of floating point): 2-element array giving ICRS (RA,Dec) in degrees, or `null` if no position can be decoded

Next Previous Up Contents
Next: Tilings
Up: Functions
Previous: Sky

STILTS - Starlink Tables Infrastructure Library Tool Set
Starlink User Note256
STILTS web page: http://www.starlink.ac.uk/stilts/
Author email: m.b.taylor@bristol.ac.uk
Mailing list: topcat-user@jiscmail.ac.uk