Misc (API documentation of hlt.language packages)
Date: 2013-01-30

hlt.language.tools

## Class Misc

- java.lang.Object
- - hlt.language.tools.Misc

-     public class Misc
      extends java.lang.Object

  This class implements a grab-bag of useful methods. If you need something that is not defined where you'd expect it although it is useful, can be reused many times, and is generic enough to warrant being used in arbitrary contexts, chances are it's in here - and if it isn't, it should be!

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.util.Iterator` | `EMPTY_ITERATOR` An empty iterator that may come handy.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Misc()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.String` | `arrayToString(double[] a)` Returns a string for the specified array of doubles as a square-bracketed comma-sparated list of its elements.
    `static java.lang.String` | `arrayToString(double[] a, java.lang.String start, java.lang.String separator, java.lang.String end)` Returns a string for the specified array of doubles.
    `static java.lang.String` | `arrayToString(int[] a)` Returns a string for the specified array of ints as a square-bracketed comma-sparated list of its elements.
    `static java.lang.String` | `arrayToString(int[] a, java.lang.String start, java.lang.String separator, java.lang.String end)` Returns a string for the specified array of ints, using the specified start, separator, and end strings.
    `static java.lang.String` | `arrayToString(java.lang.Object[] a)` Returns a string for the specified array of Objects as a square-bracketed comma-sparated list of its elements.
    `static java.lang.String` | `arrayToString(java.lang.Object[] a, java.lang.String start, java.lang.String separator, java.lang.String end)` Returns a string for the specified array of objects.
    `static boolean` | `askYesNo(java.io.PrintStream out, java.io.InputStream in, java.io.PrintStream err, java.lang.String prompt, boolean yesno)` Asks the user for a Y/N answer with the specified default answer, with default answer specified as boolean `yesno`.
    `static boolean` | `askYesNo(java.lang.String s)` Asks the user for a Y/N answer and returns it boolean interpretation - the default answer is yes.
    `static boolean` | `askYesNo(java.lang.String prompt, boolean yesno)` Asks the user for a Y/N answer with the specified default answer, with default answer specified as boolean `yesno`, using standard input/output streams.
    `static void` | `beep()` A method that beeps.
    `static boolean` | `booleanValueOf(java.lang.String s)` Returns `true` iff the given string is a positive word (i.e., true, t, yes, y).
    `static java.lang.String` | `capitalize(java.lang.String s)` Returns the string obtained from the specified string after changing its first character to a capital.
    `static java.lang.String` | `className(java.lang.Object object)` Returns the qualified name of the class of the specified object.
    `static int` | `currentYear()` Return the current year as an int.
    `static boolean` | `equal(double[] a1, double[] a2)` Returns `true` iff the two arrays have equal elements.
    `static boolean` | `equal(int[] a1, int[] a2)` Returns `true` iff the two arrays have equal elements.
    `static boolean` | `equal(java.lang.Object[] a1, java.lang.Object[] a2)` Returns `true` iff the two arrays have equal elements.
    `static java.lang.String` | `etc(int width, java.lang.Object object)` Returns a possibly truncated string form no longer than the specified width for the specified object (including trailing " ..." if the string form is longer than the specified width).
    `static void` | `forceGC()` Quietly forces garbage collection.
    `static void` | `forceGC(boolean sayit)` Forces garbage collection, and reports it on the standard error stream if the given boolean argument is `true`.
    `static void` | `forceGC(boolean sayit, java.io.PrintStream stream)` Forces garbage collection, and reports it on the specified stream if the given boolean argument is `true`.
    `static java.lang.String` | `htmlCode(char c)` Returns the HTML encoding string of the specified character.
    `static java.lang.String` | `htmlString(java.lang.String s)` Returns the string obtained from the specified string after substituting characters that are special to HTML by their HTML encoding string.
    `static boolean` | `isLowerCase(java.lang.String s)` Returns `true` iff the given string contains at least one letter, and all its letters are lower case letters.
    `static boolean` | `isUpperCase(java.lang.String s)` Returns `true` iff the given string contains at least one letter, and all its letters are upper case letters.
    `static Locatable` | `latestExtent(Locatable l1, Locatable l2)` Returns the locatable that is "further down".
    `static java.lang.String` | `letterSubstring(java.lang.String s)` Returns the substring of the given string that starts at the first letter occurrence in the string.
    `static ArrayList` | `list(java.lang.Object[] obs)` Returns an `ArrayList` containing the elements of specified array.
    `static java.lang.String` | `locationString(Locatable extent)` Returns an explicit string for the specified locatable.
    `static java.lang.String` | `locationString(Location location)` Returns an explicit string for the specified location.
    `static java.lang.String` | `minsec(long time)` Returns a string describing in min/sec the time specified in milliseconds.
    `static java.util.Calendar` | `now()` Return the current date as a `java.util.Calendar` object.
    `static java.lang.String` | `numberString(long n, int width)` Returns the string representation of the given long integer `n` using as many blank spaces on the left, using at least `width` digits in total.
    `static java.lang.String` | `numberString(long n, int width, char pad)` Returns the string representation of the given integer `n` using as many `pad` characters on the left, using at least `width` digits in total.
    `static int` | `numWidth(long n)` Returns the number of decimal digits necessary to write the given long integer `n`.
    `static java.lang.String` | `ordinal(int n)` Return the correct ordinal suffix for the specified number.
    `static java.lang.String` | `pform(int c)` Returns a printable form of the given character code.
    `static boolean` | `precedes(Locatable l1, Locatable l2)` Returns `true` if the first location "precedes" the second one.
    `static void` | `printErase(java.lang.String s)` Prints the given string on the standard output then backs over the length of it.
    `static java.lang.String` | `prompt(java.lang.String s)` Prompts the user with the specified string on stdout, then returns the string entered up to carriage return on stdin.
    `static java.lang.String` | `prompt(java.lang.String s, java.io.PrintStream out)` Prompts the user with the specified string on the specified PrintStream, then returns the string entered up to carriage return on stdin.
    `static java.lang.String` | `quotify(java.lang.String s)` Returns the string obtained from the specified string transformed so that it would give the original string when double quoted and using backslash as the escape character.
    `static java.lang.String` | `quotify(java.lang.String s, char quote, char escape)` Returns the string obtained from the specified string transformed so that it would give the original string when quoted.
    `static java.lang.String` | `repeat(int n, char c)` Returns a string of `n` `c`s.
    `static boolean` | `sameExtent(Locatable l1, Locatable l2)` Return `true` iff the two specified locatables have the same extent.
    `static boolean` | `sameLocation(Location l1, Location l2)` Return `true` iff the two specified locations are the same.
    `static java.lang.String` | `simpleClassName(java.lang.Object object)` Returns the unqualified name of the class of the specified object.
    `static java.util.AbstractList` | `sort(java.util.AbstractList a)` Sorts the specified `AbstractList` in place.
    `static java.util.AbstractList` | `sort(java.util.AbstractList a, int fst, int lst)` Sorts the elements between index fst and lst (both inclusive) in the specified `AbstractList` in place.
    `static Comparable[]` | `sort(Comparable[] a)` Sorts the specified array of comparable objects in place.
    `static Comparable[]` | `sort(Comparable[] a, int fst, int lst)` Sorts the elements between index fst and lst (both inclusive) in the specified array of comparable objects in place.
    `static java.lang.String` | `stringify(java.lang.String s)` Returns the string obtained from the specified string as an identical one except that special characters are rendered as their escape sequences.
    `static java.lang.String` | `stringify(java.lang.String s, char quote, char escape)` Returns the string obtained from the specified string as an identical one except that special characters are rendered as their escape sequences.
    `static java.lang.String` | `title(java.lang.String string, char c, int n, int length)` Returns the specified string surrounded with the specified char (with `n` on the left, and as many as needed on the right to make the `length`.
    `static java.lang.String` | `unquotify(java.lang.String s)` Returns the passed argument string deprived of any single or double quoting if any.
    `static java.lang.String` | `valueInRadix(int n, int radix)` Returns the string representation of the given integer in the given radix.
    `static java.lang.String` | `view(Queue queue, java.lang.String name, int offset, int queueWidth)` Returns a legible "view" of a queue as a String.
    `static java.lang.String` | `view(ViewableStack stack, java.lang.String name, int offset, int stackWidth)` Returns a legible "view" of a stack as a String.
    `static java.lang.String` | `zeroPaddedString(int n, int width)` Returns the string representation of the given integer `n` using as many zeros on the left, using at least `width` digits in total.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### EMPTY_ITERATOR

          public static final java.util.Iterator EMPTY_ITERATOR

      An empty iterator that may come handy.

  - ### Constructor Detail

    - #### Misc

          public Misc()

  - ### Method Detail

    - #### ordinal

          public static java.lang.String ordinal(int n)

      Return the correct ordinal suffix for the specified number.

    - #### now

          public static java.util.Calendar now()

      Return the current date as a `java.util.Calendar` object.

    - #### currentYear

          public static int currentYear()

      Return the current year as an int.

    - #### repeat

          public static java.lang.String repeat(int n,
                                char c)

      Returns a string of `n` `c`s.

    - #### title

          public static java.lang.String title(java.lang.String string,
                               char c,
                               int n,
                               int length)

      Returns the specified string surrounded with the specified char (with `n` on the left, and as many as needed on the right to make the `length`.

    - #### minsec

          public static final java.lang.String minsec(long time)

      Returns a string describing in min/sec the time specified in milliseconds.

    - #### view

          public static final java.lang.String view(ViewableStack stack,
                              java.lang.String name,
                              int offset,
                              int stackWidth)

      Returns a legible "view" of a stack as a String.

    - #### view

          public static final java.lang.String view(Queue queue,
                              java.lang.String name,
                              int offset,
                              int queueWidth)

      Returns a legible "view" of a queue as a String.

    - #### unquotify

          public static final java.lang.String unquotify(java.lang.String s)

      Returns the passed argument string deprived of any single or double quoting if any. A repeatedly quoted form will be stripped of all its layers of quotes - i.e., `unquotify("'"foo"'")` will return `foo`.

    - #### etc

          public static final java.lang.String etc(int width,
                             java.lang.Object object)

      Returns a possibly truncated string form no longer than the specified width for the specified object (including trailing " ..." if the string form is longer than the specified width).

    - #### arrayToString

          public static final java.lang.String arrayToString(int[] a,
                                       java.lang.String start,
                                       java.lang.String separator,
                                       java.lang.String end)

      Returns a string for the specified array of ints, using the specified start, separator, and end strings.

    - #### arrayToString

          public static final java.lang.String arrayToString(int[] a)

      Returns a string for the specified array of ints as a square-bracketed comma-sparated list of its elements.

    - #### arrayToString

          public static final java.lang.String arrayToString(double[] a,
                                       java.lang.String start,
                                       java.lang.String separator,
                                       java.lang.String end)

      Returns a string for the specified array of doubles.

    - #### arrayToString

          public static final java.lang.String arrayToString(double[] a)

      Returns a string for the specified array of doubles as a square-bracketed comma-sparated list of its elements.

    - #### arrayToString

          public static final java.lang.String arrayToString(java.lang.Object[] a,
                                       java.lang.String start,
                                       java.lang.String separator,
                                       java.lang.String end)

      Returns a string for the specified array of objects.

    - #### arrayToString

          public static final java.lang.String arrayToString(java.lang.Object[] a)

      Returns a string for the specified array of Objects as a square-bracketed comma-sparated list of its elements.

    - #### equal

          public static final boolean equal(int[] a1,
                      int[] a2)

      Returns `true` iff the two arrays have equal elements. NB: `null` arrays are considered equal.

    - #### equal

          public static final boolean equal(double[] a1,
                      double[] a2)

      Returns `true` iff the two arrays have equal elements. NB: `null` arrays are considered equal.

    - #### equal

          public static final boolean equal(java.lang.Object[] a1,
                      java.lang.Object[] a2)

      Returns `true` iff the two arrays have equal elements. NB: `null` arrays are considered equal.

    - #### className

          public static final java.lang.String className(java.lang.Object object)

      Returns the qualified name of the class of the specified object.

    - #### simpleClassName

          public static final java.lang.String simpleClassName(java.lang.Object object)

      Returns the unqualified name of the class of the specified object.

    - #### list

          public static final ArrayList list(java.lang.Object[] obs)

      Returns an `ArrayList` containing the elements of specified array.

    - #### sameLocation

          public static final boolean sameLocation(Location l1,
                             Location l2)

      Return `true` iff the two specified locations are the same.

    - #### sameExtent

          public static final boolean sameExtent(Locatable l1,
                           Locatable l2)

      Return `true` iff the two specified locatables have the same extent.

    - #### precedes

          public static final boolean precedes(Locatable l1,
                         Locatable l2)

      Returns `true` if the first location "precedes" the second one. That is, if the second one is nested in, or to the right of, the first one. This makes sense only for if the locatables span a the same file.

    - #### latestExtent

          public static final Locatable latestExtent(Locatable l1,
                               Locatable l2)

      Returns the locatable that is "further down". That is, the one that is nested in, or to the right of, the other. This makes sense only for if the locatables are within the same file.

    - #### locationString

          public static final java.lang.String locationString(Locatable extent)

      Returns an explicit string for the specified locatable.

    - #### locationString

          public static final java.lang.String locationString(Location location)

      Returns an explicit string for the specified location.

    - #### beep

          public static final void beep()

      A method that beeps.

    - #### stringify

          public static final java.lang.String stringify(java.lang.String s)

      Returns the string obtained from the specified string as an identical one except that special characters are rendered as their escape sequences.

    - #### stringify

          public static final java.lang.String stringify(java.lang.String s,
                                   char quote,
                                   char escape)

      Returns the string obtained from the specified string as an identical one except that special characters are rendered as their escape sequences. The last two arguments are the quote and escape characters.

    - #### quotify

          public static final java.lang.String quotify(java.lang.String s)

      Returns the string obtained from the specified string transformed so that it would give the original string when double quoted and using backslash as the escape character.

    - #### quotify

          public static final java.lang.String quotify(java.lang.String s,
                                 char quote,
                                 char escape)

      Returns the string obtained from the specified string transformed so that it would give the original string when quoted. The specified `quote` and `escape` are the quote and escape characters, respectively.

    - #### capitalize

          public static final java.lang.String capitalize(java.lang.String s)

      Returns the string obtained from the specified string after changing its first character to a capital.

    - #### isLowerCase

          public static final boolean isLowerCase(java.lang.String s)

      Returns `true` iff the given string contains at least one letter, and all its letters are lower case letters.

    - #### isUpperCase

          public static final boolean isUpperCase(java.lang.String s)

      Returns `true` iff the given string contains at least one letter, and all its letters are upper case letters.

    - #### htmlString

          public static final java.lang.String htmlString(java.lang.String s)

      Returns the string obtained from the specified string after substituting characters that are special to HTML by their HTML encoding string.

    - #### htmlCode

          public static final java.lang.String htmlCode(char c)

      Returns the HTML encoding string of the specified character.

    - #### askYesNo

          public static final boolean askYesNo(java.lang.String s)

      Asks the user for a Y/N answer and returns it boolean interpretation - the default answer is yes.

    - #### askYesNo

          public static final boolean askYesNo(java.lang.String prompt,
                         boolean yesno)

      Asks the user for a Y/N answer with the specified default answer, with default answer specified as boolean `yesno`, using standard input/output streams.

    - #### askYesNo

          public static final boolean askYesNo(java.io.PrintStream out,
                         java.io.InputStream in,
                         java.io.PrintStream err,
                         java.lang.String prompt,
                         boolean yesno)

      Asks the user for a Y/N answer with the specified default answer, with default answer specified as boolean `yesno`.

    - #### prompt

          public static final java.lang.String prompt(java.lang.String s,
                                java.io.PrintStream out)

      Prompts the user with the specified string on the specified PrintStream, then returns the string entered up to carriage return on stdin.

    - #### prompt

          public static final java.lang.String prompt(java.lang.String s)

      Prompts the user with the specified string on stdout, then returns the string entered up to carriage return on stdin.

    - #### printErase

          public static final void printErase(java.lang.String s)

      Prints the given string on the standard output then backs over the length of it. This is useful for an in-place counter.

    - #### letterSubstring

          public static final java.lang.String letterSubstring(java.lang.String s)

      Returns the substring of the given string that starts at the first letter occurrence in the string. If none returns the full string.

    - #### pform

          public static final java.lang.String pform(int c)

      Returns a printable form of the given character code.

    - #### numberString

          public static final java.lang.String numberString(long n,
                                      int width,
                                      char pad)

      Returns the string representation of the given integer `n` using as many `pad` characters on the left, using at least `width` digits in total.

    - #### numberString

          public static final java.lang.String numberString(long n,
                                      int width)

      Returns the string representation of the given long integer `n` using as many blank spaces on the left, using at least `width` digits in total.

    - #### zeroPaddedString

          public static final java.lang.String zeroPaddedString(int n,
                                          int width)

      Returns the string representation of the given integer `n` using as many zeros on the left, using at least `width` digits in total.

    - #### numWidth

          public static final int numWidth(long n)

      Returns the number of decimal digits necessary to write the given long integer `n`.

    - #### booleanValueOf

          public static final boolean booleanValueOf(java.lang.String s)

      Returns `true` iff the given string is a positive word (i.e., true, t, yes, y). It is case independent.

    - #### valueInRadix

          public static final java.lang.String valueInRadix(int n,
                                      int radix)

      Returns the string representation of the given integer in the given radix.

    - #### forceGC

          public static final void forceGC()

      Quietly forces garbage collection.

    - #### forceGC

          public static final void forceGC(boolean sayit)

      Forces garbage collection, and reports it on the standard error stream if the given boolean argument is `true`.

    - #### forceGC

          public static final void forceGC(boolean sayit,
                     java.io.PrintStream stream)

      Forces garbage collection, and reports it on the specified stream if the given boolean argument is `true`.

    - #### sort

          public static final Comparable[] sort(Comparable[] a)

      Sorts the specified array of comparable objects in place. It assumes that the class of objects stored in the array implements the `hlt.language.util.Comparable` interface. The algorithm used is (non-recursive) QuickSort. It returns the specified array.

    - #### sort

          public static final Comparable[] sort(Comparable[] a,
                          int fst,
                          int lst)

      Sorts the elements between index fst and lst (both inclusive) in the specified array of comparable objects in place. It assumes that the class of objects stored in the array implements the `hlt.language.util.Comparable` interface. The algorithm used is (non-recursive) QuickSort. It returns the specified array.

    - #### sort

          public static final java.util.AbstractList sort(java.util.AbstractList a)

      Sorts the specified `AbstractList` in place. It assumes that the class of objects stored in the `AbstractList` implements the `hlt.language.util.Comparable` interface. The algorithm used is (non-recursive) QuickSort. It returns the specified `AbstractList`.

    - #### sort

          public static final java.util.AbstractList sort(java.util.AbstractList a,
                                    int fst,
                                    int lst)

      Sorts the elements between index fst and lst (both inclusive) in the specified `AbstractList` in place. It assumes that the class of objects stored in the `AbstractList` implements the `hlt.language.util.Comparable` interface. The algorithm used is (non-recursive) QuickSort. It returns the specified `AbstractList`.