Package jmri.util

Class StringUtil

java.lang.Object
jmri.util.StringUtil
public class StringUtil extends Object
Common utility methods for working with Strings.

We needed a place to refactor common string-processing idioms in JMRI code, so this class was created. It's more of a library of procedures than a real class, as (so far) all of the operations have needed no state information.

In some cases, these routines use a Java 1.3 or later method, falling back to an explicit implementation when running on Java 1.1

  • Field Details

  • Method Details

    • getStateFromName

      @CheckReturnValue public static int getStateFromName(String name, @Nonnull int[] states, @Nonnull String[] names)
      Starting with two arrays, one of names and one of corresponding numeric state values, find the state value that matches a given name string
      Parameters:
      name - the name to search for
      states - the state values
      names - the name values
      Returns:
      the state or -1 if none found

    • getNamesFromStateMasked

      @Nonnull @CheckReturnValue public static String[] getNamesFromStateMasked(int state, @Nonnull int[] states, @Nonnull int[] masks, @Nonnull String[] names)
      Starting with three arrays, one of names, one of corresponding numeric state values, and one of masks for the state values, find the name string(s) that match a given state value
      Parameters:
      state - the given state
      states - the state values
      masks - the state masks
      names - the state names
      Returns:
      names matching the given state or an empty array

    • getNameFromState

      @CheckReturnValue @CheckForNull public static String getNameFromState(int state, @Nonnull int[] states, @Nonnull String[] names)
      Starting with two arrays, one of names and one of corresponding numeric state values, find the name string that matches a given state value. Only one may be returned.
      Parameters:
      state - the given state
      states - the state values
      names - the state names
      Returns:
      the first matching name or null if none found

    • getNamesFromState

      @Nonnull @CheckReturnValue public static String[] getNamesFromState(int state, @Nonnull int[] states, @Nonnull String[] names)
      Starting with two arrays, one of names, one of corresponding numeric state values, find the name string(s) that match a given state value.

      State is considered to be bit-encoded, so that its bits are taken to represent multiple independent states.

      e.g. for 3, [1, 2, 4], ["A","B","C"], the method would return ["A","B"]

      Values of 0 are only included if the state is 0, zero is NOT matched for all numbers.

      Parameters:
      state - the given state
      states - the state values
      names - the state names
      Returns:
      names matching the given state or an empty array

    • twoHexFromInt

      @CheckReturnValue @Nonnull public static String twoHexFromInt(int val)
      Convert an integer to an exactly two hexadecimal characters string
      Parameters:
      val - the integer value
      Returns:
      String exactly two characters long

    • appendTwoHexFromInt

      @CheckReturnValue @Nonnull public static String appendTwoHexFromInt(int val, @Nonnull String inString)
      Quickly append an integer to a String as exactly two hexadecimal characters
      Parameters:
      val - Value to append in hex
      inString - String to be extended
      Returns:
      String exactly two characters long

    • to8Bits

      @CheckReturnValue @Nonnull public static String to8Bits(int val, boolean msbLeft)
      Convert a small number to eight 1/0 characters.
      Parameters:
      val - the number to convert
      msbLeft - true if the MSB is on the left of the display
      Returns:
      a string of binary characters

    • hexStringFromBytes

      @CheckReturnValue @Nonnull public static String hexStringFromBytes(@Nonnull byte[] bytes)
      Create a String containing hexadecimal values from a byte[]. eg. byte[]{1,2,3,10} will return String "01 02 03 0A " eg. byte[]{-1} will return "FF " eg. byte[]{(byte)256} will return "00 " eg. byte[]{(byte)257} will return "01 "
      Parameters:
      bytes - byte array. Can be zero length, but must not be null.
      Returns:
      String of hex values, ala "01 02 0A B1 21 ".

    • hexStringFromInts

      @CheckReturnValue @Nonnull public static String hexStringFromInts(@Nonnull int[] v)
      Convert an array of integers into a single spaced hex. string. Each int value will receive 2 hex characters.

      eg. int[]{1,2,3,10} will return "01 02 03 0A " eg. int[]{-1} will return "FF " eg. int[]{256} will return "00 " eg. int[]{257} will return "01 "

      Parameters:
      v - the array of integers. Can be zero length, but must not be null.
      Returns:
      the formatted String or an empty String

    • bytesFromHexString

      @CheckReturnValue @Nonnull public static byte[] bytesFromHexString(@Nonnull String s)
      Create a byte[] from a String containing hexadecimal values.
      Parameters:
      s - String of hex values, ala "01 02 0A B1 21".
      Returns:
      byte array, with one byte for each pair. Can be zero length, but will not be null.

    • intBytesWithTotalFromNonSpacedHexString

      @Nonnull public static int[] intBytesWithTotalFromNonSpacedHexString(@Nonnull String s, boolean headerTotal)
      Create an int[] from a String containing paired hexadecimal values.

      Option to include array length as leading array value

      eg. #("01020AB121",true) returns int[5, 1, 2, 10, 177, 33]

      eg. ("01020AB121",false) returns int[1, 2, 10, 177, 33]

      Parameters:
      s - String of hex value pairs, eg "01020AB121".
      headerTotal - if true, adds index [0] with total of pairs found
      Returns:
      int array, with one field for each pair.

    • getHexDigit

      public static int getHexDigit(int index, @Nonnull String byteString)
      Get a single hex digit from a String.

      eg. getHexDigit(0,"ABCDEF") returns 10 eg. getHexDigit(3,"ABCDEF") returns 14

      Parameters:
      index - digit offset, 0 is very first digit on left.
      byteString - String of hex values, eg "01020AB121".
      Returns:
      hex value of single digit

    • getByte

      public static int getByte(int b, @Nonnull String byteString)
      Get a single hex data byte from a string

      eg. getByte(2,"0102030405") returns 3

      Parameters:
      b - The byte offset, 0 is byte 1
      byteString - the whole string, eg "01AB2CD9"
      Returns:
      The value, else 0

    • fullTextToHexArray

      @CheckReturnValue @Nonnull public static byte[] fullTextToHexArray(@Nonnull String s, int numBytes)
      Create a hex byte[] of Unicode character values from a String containing full text (non hex) values.

      eg fullTextToHexArray("My FroG",8) would return byte[0x4d,0x79,0x20,0x46,0x72,0x6f,0x47,0x20]

      Parameters:
      s - String, eg "Test", value is trimmed to max byte length
      numBytes - Number of bytes expected in return ( eg. to match max. message size )
      Returns:
      hex byte array, with one byte for each character. Right padded with empty spaces (0x20)

    • sortUpperCase

      public static void sortUpperCase(@Nonnull Object[] values)
      This is a case-independent lexagraphic sort. Identical entries are retained, so the output length is the same as the input length.
      Parameters:
      values - the Objects to sort

    • numberSort

      public static void numberSort(@Nonnull String[] values) throws NumberFormatException
      Sort String[] representing numbers, in ascending order.
      Parameters:
      values - the Strings to sort
      Throws:
      NumberFormatException - if string[] doesn't only contain numbers

    • parenQuote

      @CheckReturnValue @CheckForNull public static String parenQuote(@CheckForNull String in)
      Quotes unmatched closed parentheses; matched ( ) pairs are left unchanged. If there's an unmatched ), quote it with \, and quote \ with \ too.
      Parameters:
      in - String potentially containing unmatched closing parenthesis
      Returns:
      null if given null

    • parenUnQuote

      @CheckReturnValue @CheckForNull static String parenUnQuote(@CheckForNull String in)
      Undo parenQuote
      Parameters:
      in - the input String
      Returns:
      null if given null

    • splitParens

      @CheckReturnValue @Nonnull public static List<String> splitParens(@CheckForNull String in)

    • arrayToString

      @CheckReturnValue @Nonnull public static <E> String arrayToString(@Nonnull E[] v)
      Convert an array of objects into a single string. Each object's toString value is displayed within square brackets and separated by commas.
      Type Parameters:
      E - the array class
      Parameters:
      v - the array to process
      Returns:
      a string; empty if the array was empty

    • arrayToString

      @CheckReturnValue @Nonnull public static String arrayToString(@Nonnull byte[] v)
      Convert an array of bytes into a single string. Each element is displayed within square brackets and separated by commas.
      Parameters:
      v - the array of bytes
      Returns:
      the formatted String, or an empty String

    • arrayToString

      @CheckReturnValue @Nonnull public static String arrayToString(@Nonnull int[] v)
      Convert an array of integers into a single string. Each element is displayed within square brackets and separated by commas.
      Parameters:
      v - the array of integers
      Returns:
      the formatted String or an empty String

    • padString

      @CheckReturnValue public static String padString(@Nonnull String value, int length)
      Trim a text string to length provided and (if shorter) pad with trailing spaces. Removes 1 extra character to the right for clear column view.
      Parameters:
      value - contents to process
      length - trimming length
      Returns:
      trimmed string, left aligned by padding to the right

    • getFirstIntFromString

      @CheckReturnValue public static int getFirstIntFromString(@Nonnull String str)
      Return the first int value within a string eg :X X123XX456X: will return 123 eg :X123 456: will return 123
      Parameters:
      str - contents to process
      Returns:
      first value in int form , -1 if not found

    • getLastIntFromString

      @CheckReturnValue public static int getLastIntFromString(@Nonnull String str)
      Return the last int value within a string eg :XX123XX456X: will return 456 eg :X123 456: will return 456
      Parameters:
      str - contents to process
      Returns:
      last value in int form , -1 if not found

    • incrementLastNumberInString

      @CheckForNull public static String incrementLastNumberInString(@Nonnull String str, int increment)
      Increment the last number found in a string.
      Parameters:
      str - Initial string to increment.
      increment - number to increment by.
      Returns:
      null if not possible, else incremented String.

    • replaceLast

      @CheckReturnValue @Nonnull public static String replaceLast(@Nonnull String string, @Nonnull String from, @Nonnull String to)
      Replace the last occurance of string value within a String eg from ABC to DEF will convert XXABCXXXABCX to XXABCXXXDEFX
      Parameters:
      string - contents to process
      from - value within string to be replaced
      to - new value
      Returns:
      string with the replacement, original value if no match.

    • concatTextHtmlAware

      public static String concatTextHtmlAware(String baseText, String extraText)
      Concatenates text Strings where either could possibly be in HTML format (as used in many Swing components).

      Ensures any appended text is added within the <html>...</html> element, if there is any.

      Parameters:
      baseText - original text
      extraText - text to be appended to original text
      Returns:
      Combined text, with a single enclosing <html>...</html> element (only if needed).

    • stripHtmlTags

      public static String stripHtmlTags(String originalText)
      Removes HTML tags from a String. Replaces HTML line breaks with newline characters from a given input string.
      Parameters:
      originalText - The input string that may contain HTML tags.
      Returns:
      A cleaned string with HTML tags removed.