Method Detail

• replace

  public static java.lang.String replace(java.lang.String s,
                         java.lang.String oldSubstring,
                         java.lang.String newSubstring)

  Returns a new string resulting from replacing all occurrences of oldSubstring in the s source string with newSubstring.

  If s == null, no exceptions are thrown; in this case, the method returns null.

  If oldSubstring does not occur in the the s source string, then a reference to s object is returned.

  This method can be a useful addition to the standard String.replace method, especially for debug output. It works more quickly than Java 1.4 String.replaceAll method, and is more simple in use.

  Parameters:

  s - the string

  oldSubstring - the old substring

  newSubstring - the new substring

  Returns:

  a string derived from s string by replacing every occurrence of oldSubstring with newSubstring

  Throws:

  java.lang.NullPointerException - if oldSubstring == null or newSubstring == null

  java.lang.IllegalArgumentException - if oldSubstring.length() == 0

• avoidDebugSignalsForExceptions

  public static java.lang.String avoidDebugSignalsForExceptions(java.lang.String s)

  Replaces every char sequence "Exception" in the string s with the char sequence "[[E]]xception".

  It allows to avoid wrong signals generated by some IDEs when they detect "Exception" word in the standard application output while debugging the program. For example, Borland JavaBuilder(TM) sounds a clank every time when the debugged application prints "Exception" into System.out or System.err. It's a good idea usually, when the application prints standard exception information (for example, by e.printStackTrace() call). But it can be very bad if you need to print some debugging text containing a lot of "Exception" words while normal execution of the application.

  This method is called internally by print(String) and println(String) methods of this class, if you set the corresponding flag by setAutomaticAvoidingDebugSignalsForExceptions(boolean) method.

  Parameters:

  s - the corrected string; can be null

  Returns:

  replace(s,"Exception","[[E]]xception"); null if s == null

  See Also:

  print(String), println(String), setAutomaticAvoidingDebugSignalsForExceptions(boolean)

• replaceLFToLineSeparator

  public static java.lang.String replaceLFToLineSeparator(java.lang.String s)

  Replaces every "\n" character in the string s with GlobalProperties.LINE_SEPARATOR string.

  If "\n" character is already a part of some line separator, it is not replaced. So, you can also apply method to texts where the lines are separated by GlobalProperties.LINE_SEPARATOR.

  It can simplify generation of a text with lines separated by GlobalProperties.LINE_SEPARATOR.

  This method is called internally by print(String) and println(String) methods of this class.

  Parameters:

  s - the corrected string; can be null

  Returns:

  replace(s,"\n",GlobalProperties.LINE_SEPARATOR); null if s == null

  See Also:

  print(String), println(String)

• dup

  public static java.lang.String dup(char c,
                     int len)

  Returns a string consisting of len copies of the specified character c.

  Parameters:

  c - the character that is duplicated

  len - the number of copies of c characters in the result string

  Returns:

  a string consisting of len characters, each character is equal to c

• pad

  public static java.lang.String pad(java.lang.String s,
                     int padLen)

  If padLen < s.length(), returns a reference to the original s string object; in other case, returns the s padded leftward to padLen length by the space character:

      dup(' ', padLen - s.length()) + s
   

  Parameters:

  s - the string that should be padded

  padLen - the minimal length of the resulting string

  Returns:

  the string padded leftward (if necessary) to the padLen length by the space character

• rightPad

  public static java.lang.String rightPad(java.lang.String s,
                          int padLen)

  If padLen < s.length(), returns a reference to the original s string object; in other case, returns the s padded rightward to padLen length by the space character:

      s + dup(' ', padLen - s.length())
   

  Parameters:

  s - the string that should be padded

  padLen - the minimal length of the resulting string

  Returns:

  the string padded rightward (if necessary) to the padLen length by the space character

• pad

  public static java.lang.String pad(java.lang.String s,
                     int padLen,
                     char pad,
                     boolean right)

  If padLen < s.length(), returns a reference to the original s string object; in other case, returns the s padded leftward or rightward to padLen length by the given pad character:

      right? s + dup(pad, padLen - s.length()): dup(pad, padLen - s.length()) + s
   

  Parameters:

  s - the string that should be padded

  padLen - the minimal length of the resulting string

  pad - the character used for padding

  right - if true, the string is padded rightward, else leftward

  Returns:

  the string padded (if necessary) to the padLen length by the pad character

• pad

  public static java.lang.String pad(int v,
                     int padLen)

  Equivalent to

      pad(String.valueOf(v),padLen)
   

  Parameters:

  v - the integer number that should be converted to string and padded

  padLen - the minimal number of characters of the resulting string

  Returns:

  a decimal representation of the given number, padded leftward (if necessary) to the padLen length by the space character

  See Also:

  pad(String, int)

• pad

  public static java.lang.String pad(long v,
                     int padLen)

  Equivalent to

      pad(String.valueOf(v),padLen)
   

  Parameters:

  v - the long number that should be converted to string and padded

  padLen - the minimal number of characters of the resulting string

  Returns:

  a decimal representation of the given number, padded leftward (if necessary) to the padLen length by the space character

  See Also:

  pad(String, int)

• deTab

  public static java.lang.String deTab(java.lang.String s,
                       int tabLen)

  Equivalent to

      deTab(s,tabLen,'\n')
   

  Parameters:

  s - the multiline text where all tab characters (\t) should be replaced with spaces

  tabLen - every \t charater corresponds to tabLen positions

  Returns:

  an original text where all tab characters (\t) are replaced with spaces

  See Also:

  deTab(String, int, char)

• deTab

  public static java.lang.String deTab(java.lang.String s,
                       int tabLen,
                       char lineSeparator)

  Performs standard detab operation with the given tabulation length. All tab characters '\t' are replaced with corresponding number of spaces ' '. This method assumes that the lines in the s text are separated by one character lineSeparator or by a sequence of characters where the last character is lineSeparator. In other words, the position in the line of the first character after each lineSeparator is 0. (We consider that the positions in lines start from 0, not from 1.)

  For example:

      deTab("\t",4,'\n') == "    "
      deTab("aa\tbb",4,'\n') == "aa  bb"
      deTab("aa\t\r\n\tbb",4,'\n') == "aa  \r\n    bb"
   but
      deTab("aa\t\n\r\tbb",4,'\n') == "aa  \n\r   bb"
   

  Parameters:

  s - the multiline text where all tab characters (\t) should be replaced with spaces

  tabLen - every \t charater corresponds to tabLen positions

  lineSeparator - the character used for line separation, or the last character in the sequence that is used for line separation

  Returns:

  an original text where all tab characters (\t) are replaced with spaces

• deTab

  public static java.lang.String deTab(java.lang.String s,
                       int[] tabPositions)

  Equivalent to

      deTab(s,tabPositions,'\n')
   

  Parameters:

  s - the multiline text where all tab characters (\t) should be replaced with spaces

  tabPositions - tabulation positions

  Returns:

  an original text where all tab characters (\t) are replaced with spaces

  See Also:

  deTab(String, int), deTab(String, int[], char)

• deTab

  public static java.lang.String deTab(java.lang.String s,
                       int[] tabPositions,
                       char lineSeparator)

  Performs detab operation with the given set of tabulation positions. Every tab character '\t' in each line of the text s is replaced with several spaces ' ' (at least by one space) so that the index of the next character in this line becomes equal to the nearest next element of tabPositions array which is >= the current position in the line. If there are no available elements in tabPositions (the array is exhausted), '\t' character is merely replaced with space ' '.

  More simple method deTab(String, int, char) is equivalent to the call of this one when tabPositions array contains an "infinite" (large enough) sequence of integer numbers 8, 16, 24, ..., 8*n, ...

  This method assumes that the lines in the s text are separated by one character lineSeparator or by a sequence of characters where the last character is lineSeparator. In other words, the position in the line of the first character after each lineSeparator is 0. (We consider that the positions in lines start from 0, not from 1.)

  For example:

      deTab("\t",new int[] {2},'\n') == "  "
      deTab("aa\tbb",new int[0],'\n') == "aa bb"
      deTab("aa\tbb\tcc",new int[] {4,10,20},'\n') == "aa  bb    cc"
   but
      deTab("aa\tbb\tcc",new int[] {1,10,20},'\n') == "aa        bb        cc"
   

  In the last case, the first element of tabPositions array is less than the position of the first '\t' character; so, this element was skipped, and elements 10 and 20 were used.

  This method is very convenient for generating logs and reports formatted by spaces.

  Parameters:

  s - the multiline text where all tab characters (\t) should be replaced with spaces

  tabPositions - tabulation positions

  lineSeparator - the character used for line separation, or the last character in the sequence that is used for line separation

  Returns:

  an original text where all tab characters (\t) are replaced with spaces

  See Also:

  deTab(String, int, char)

• hex

  public static java.lang.String hex(byte v)

  Returns a hexadecimal unsigned representation of the byte argument. Unlike Integer.toHexString(v) call, the result always contains 2 digits (leaded by '0' if needed).

  Parameters:

  v - the byte argument

  Returns:

  its hexadecimal representation (2 characters)

• hex

  public static java.lang.String hex(short v)

  Returns a hexadecimal unsigned representation of the short argument. Unlike Integer.toHexString(v) call, the result always contains 4 digits (leaded by '0' if needed).

  Parameters:

  v - the short argument

  Returns:

  its hexadecimal representation (4 characters)

• hex

  public static java.lang.String hex(int v)

  Returns a hexadecimal unsigned representation of the int argument. Unlike Integer.toHexString(v) call, the result always contains 8 digits (leaded by '0' if needed).

  Parameters:

  v - the int argument

  Returns:

  its hexadecimal representation (8 characters)

• hex

  public static java.lang.String hex(long v)

  Returns a hexadecimal unsigned representation of the long argument. Unlike Long.toHexString(v) call, the result always contains 16 digits (leaded by '0' if needed).

  Parameters:

  v - the long argument

  Returns:

  its hexadecimal representation (16 characters)

• dec

  public static java.lang.String dec(double v,
                     int d)

  Returns the string decimal representation of the double argument with d digits after the decimal point. If d <= 0, the mantissa is not included in the result.

  Examples:

      dec(100*Math.PI,5) == "314.15927",
      dec(100.0/3.0,1) == "33.3",
      dec(-2.0/3.0,0) == "-1"
   

  As for String.valueOf(v) call, the result is always written in american (scientific) standard, regardless of the current regional settings.

  Parameters:

  v - the double number

  d - the number of digits after the decimal point

  Returns:

  the decimal representation of the given number

  See Also:

  exp(double, int)

• exp

  public static java.lang.String exp(double v,
                     int d)

  Returns the string decimal representation of the double argument in exponent form ("scientific" notation) with d digits after the decimal point. If d <= 0, the mantissa is not included in the result.

  Examples:

      exp(100*Math.PI,5) == "3.14159E2",
      exp(100.0/3.0,5) == "3.3E1",
      dec(-2.0/3.0,0) == "-7E-1"
   

  As for String.valueOf(v) call, the result is always written in american (scientific) standard, regardless of the current regional settings.

  Parameters:

  v - the double number

  d - the number of digits after the decimal point

  Returns:

  the exponent-form representation of the given number

  See Also:

  dec(double, int)

• dec

  public static java.lang.String dec(double v,
                     int d,
                     int padLen)

  Equivalent to

      pad(dec(v,d),padLen)
   

  Parameters:

  v - the double number

  d - the number of digits after the decimal point

  padLen - the minimal number of characters in the result

  Returns:

  the decimal representation of the given number, padded leftward (if necessary) to the padLen length by the space character

  See Also:

  exp(double, int, int)

• exp

  public static java.lang.String exp(double v,
                     int d,
                     int padLen)

  Equivalent to

      pad(exp(v,d),padLen)
   

  Parameters:

  v - the double number

  d - the number of digits after the decimal point

  padLen - the minimal number of characters in the result

  Returns:

  the exponent-form representation of the given number, padded leftward (if necessary) to the padLen length by the space character

  See Also:

  dec(double, int, int)

• spaced

  public static java.lang.String spaced(int v,
                        char space)

  Equivalent to

      spaced(v,space)
   

  Parameters:

  v - the integer number

  space - the character used for separating terns of digits

  Returns:

  the decimal representation of the given number in the well-readable form

• spaced

  public static java.lang.String spaced(long v,
                        char space)

  Returns the string decimal representation of the long integer argument where all terns of digits (from the right to the left) are separated by the given space character. The result does not regard of the current regional settings. Convenient for showing large integer numbers.

  Examples:

      spaced(345234,' ') == "345234"
      spaced(-2234,',') == "-2,234"
      spaced(22,' ') == "22"
   

  Parameters:

  v - the integer number

  space - the character used for separating terns of digits

  Returns:

  the decimal representation of the given number in the well-readable form

• abc

  public static java.lang.String abc(int v)

  Equivalent to

      abc((long)v)
   

  Parameters:

  v - the integer number

  Returns:

  the "spreadsheet" representation of the given number (used for columns in most spreadsheets)

  See Also:

  parseLongAbc(String)

• abc

  public static java.lang.String abc(long v)

  Returns the representation of the integer argument in a special "spreadsheet" form: 0 is represented as "A", 1 as "B", 2 as "C", then "D", "E", ..., "Z", "AA", "AB", ..., "AZ", "BA", "AB", ..., "ZY", "ZZ", "AAA", "AAB", ... For negative numbers, minus character is added as for usual representation: -1 is represented as "-B", -2 as "-C", etc.

  Parameters:

  v - the integer number

  Returns:

  the "spreadsheet" representation of the given number (used for columns in most spreadsheets)

  See Also:

  parseLongAbc(String)

• parseLongAbc

  public static long parseLongAbc(java.lang.String s)

  Returns such an integer number x that abc(x).equals(s).

  Parameters:

  s - the string representation of some unknown number in "spreadsheet" form

  Returns:

  the unknown number

  Throws:

  java.lang.NumberFormatException - if s is not a valid "spreadsheet" representation of an integer number

  See Also:

  abc(int), abc(long)

• join

  public static java.lang.String join(java.lang.Object o,
                      java.lang.String separator)

  If o is an instance of Java array, standard collection, map (or Java 1 Dictionary), Iterator (or Java 1 Enumeration), joins and returns as a string the standard string representations for all elements of this array (or collection, or all objects returned by the iterator), separating elements by the given separator. For all kinds of maps, joins "key=value" pairs instead elements. For null, returns an empty string. For all other classes of o object, throws an exception.

  Convenient while debugging the code processing not-too-large arrays and collections.

  Examples:

      join(new int[] {1,2,3},",") == "1,2,3"
      join(new ArrayList(),";") == ""
      join(null,",") == ""
   

  Parameters:

  o - the given array, collection, map, iterator, or null value

  separator - the string used for separating elements

  Returns:

  the string representations of all elements joined into one string

  Throws:

  java.lang.IllegalArgumentException - if the class of o argument is unsuitable

• print

  public static void print(java.lang.String value)

  Prints the given string on System.out. Unlike the standard System.out.print method, this one perform the following additional actions.

  1. The replacements provided by replaceLFToLineSeparator(String) are performed ("value = replaceLFToLineSeparator(value)"). So, this method can be safely use for printing several lines in one simple call, such as

         Out.print("First line\nSecond line")

  2. Then, if the global flag, customized by setAutomaticAvoidingDebugSignalsForExceptions(boolean) method, is set, the replacements provided by avoidDebugSignalsForExceptions(String) are performed ("value = avoidDebugSignalsForExceptions(value)").
  3. If some print delay was set by setPrintDelay(long) call, then the resulting string will not be printed immediately. Instead, it will be added to an internal buffer that will be fully printed (using System.out.print(buffer) call) after the specified delay following the last call of this method (or println(String) method, or printNoCorrections(String)). If no print delay was specified, the resulting string will be just printed by System.out.print(value) call. Such a delay can greatly increase output performance, especially while debugging under some IDE.

  Parameters:

  value - the printed string; if null, the "null" string will be printed

  See Also:

  replaceLFToLineSeparator(String), avoidDebugSignalsForExceptions(String), setAutomaticAvoidingDebugSignalsForExceptions(boolean), flush(), setPrintDelay(long), println(String)

• printFlush

  public static void printFlush(java.lang.String value)

  A brief equivalent of two print(value); flush() calls.

  Parameters:

  value - the printed string

  See Also:

  print(String), flush()

• println

  public static void println()

  A brief equivalent of println("") call (or print("\n"): remind that print method automatically replaces "\n" with GlobalProperties.LINE_SEPARATOR).

  See Also:

  print(String), println(String)

• printlnFlush

  public static void printlnFlush(java.lang.String value)

  A brief equivalent of two println(value); flush() calls.

  Parameters:

  value - the printed string

  See Also:

  println(String), flush()

• println

  public static void println(java.lang.String value)

  This method differs from System.out.println in the same respects as the print(String) method differs from System.out.print. It's equivalent to

      print(value + "\n");
   

  call. (print call automatically replaces "\n" with GlobalProperties.LINE_SEPARATOR.)

  Parameters:

  value - the printed string (followed by line separator).

  See Also:

  replaceLFToLineSeparator(String), avoidDebugSignalsForExceptions(String), setAutomaticAvoidingDebugSignalsForExceptions(boolean), flush(), setPrintDelay(long), print(String)

• printNoCorrections

  public static void printNoCorrections(java.lang.String value)

  An analog of print(String) method that doesn't perform any replacements in the value string. So, it only performs a delay before printing (if it was set by setPrintDelay(long) call) in addition to standard System.out.print actions.

  Parameters:

  value - the printed string

  See Also:

  print(String)

• flush

  public static void flush()

  Immediately flushs the buffer filled by previous calls of print(String), println(String), printNoCorrections(String) to the System.out. Does nothing if no positive delay was specified by setPrintDelay(long) call.

  Also, regardless on the delay value, this method calls flush() methods for all objects registered by addFlusher(Out.Flusher) method.

  This method is useful only if you need to synchronize the output performed by this class and the standard output tools such as direct System.out.println calls or printing to System.err (that is not buffered by this class at all).

  See Also:

  print(String), println(String), setPrintDelay(long)

• setPrintDelay

  public static void setPrintDelay(long ms)

  Sets the delay performed after the last call of print(String), println(String), printNoCorrections(String) methods until the moment when the printed text will be really sent to System.out (by System.out.print call). This value is global for this class and usually should be set only once at the start of your application.

  Parameters:

  ms - new delay in milliseconds; 0 value (which is default) means that no delay will be performed

  Throws:

  java.lang.IllegalArgumentException - if ms < 0

  See Also:

  print(String), println(String), flush()

• getPrintDelay

  public static long getPrintDelay()

  Returns the print delay set by the last setPrintDelay(long) call. Return (0 before the first call of setPrintDelay(long).

  Returns:

  the print delay set by the last setPrintDelay(long) call

• setAutomaticAvoidingDebugSignalsForExceptions

  public static void setAutomaticAvoidingDebugSignalsForExceptions(boolean value)

  Sets the flag defining whether print(String) and println(String) methods should perform replacements provided by avoidDebugSignalsForExceptions(String) method in the printed text. This flag is global for this class and usually should be set only once at the start of your application. Default value of this flag if false (no replacements). We recommend to set this flag to true in large applications that use console for debugging needs.

  Parameters:

  value - new value of this flag

  See Also:

  print(String), println(String), avoidDebugSignalsForExceptions(String)

• isAutomaticAvoidingDebugSignalsForExceptions

  public static boolean isAutomaticAvoidingDebugSignalsForExceptions()

  Returns the global flag set by the last setAutomaticAvoidingDebugSignalsForExceptions(boolean) call (false by default).

  Returns:

  the global flag set by the last setAutomaticAvoidingDebugSignalsForExceptions(boolean) call

• addFlusher

  public static void addFlusher(Out.Flusher flusher)

  Registers (adds to the internal list) a flusher, that (it's flush() method) will be called in the flush() method.

  Parameters:

  flusher - New registered flusher.

  See Also:

  removeFlusher(Out.Flusher), flush()

• removeFlusher

  public static void removeFlusher(Out.Flusher flusher)

  Deregisters (removes from the internal list) the given flusher.

  Parameters:

  flusher - New registered flusher.

  See Also:

  addFlusher(Out.Flusher), flush()