net.sf.okapi.common

## Class Util

- java.lang.Object
- - net.sf.okapi.common.Util

-     public final class Util
      extends java.lang.Object

  Collection of various all-purpose helper functions.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Util.SUPPORTED_OS` Enumeration of supported OSes

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `INPUT_ROOT_DIRECTORY_VAR` Name of the input root directory variable.
    `static java.lang.String` | `LINEBREAK_DOS` Line-break string for DOS/Windows.
    `static java.lang.String` | `LINEBREAK_MAC` Line-break string for Macintosh
    `static java.lang.String` | `LINEBREAK_UNIX` Line-break string for Unix/Linux
    `static java.lang.String` | `MTFLAG` Shared flag indicating a translation that was generated using machine translation.
    `static java.lang.String` | `ROOT_DIRECTORY_VAR` Name of the root directory variable.
    `static java.lang.String` | `RTF_ENDCODE` Default RTF style for ending an external code.
    `static java.lang.String` | `RTF_ENDINLINE` Default RTF style for ending an internal code.
    `static java.lang.String` | `RTF_ENDMARKER` Default RTF style for ending an in-between source/target marker.
    `static java.lang.String` | `RTF_MIDMARKER1` Default RTF style for the first half of a middle part of an in-between source/target marker.
    `static java.lang.String` | `RTF_MIDMARKER2` Default RTF style for the second half of a middle part of an in-between source/target marker.
    `static java.lang.String` | `RTF_STARTCODE` Default RTF style for starting an external code.
    `static java.lang.String` | `RTF_STARTINLINE` Default RTF style for starting an internal code.
    `static java.lang.String` | `RTF_STARTMARKER` Default RTF style for starting an in-between source/target marker.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Util()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.String` | `buildPath(java.lang.String... parts)` Builds a path from given parts.
    `static java.io.PrintWriter` | `charsetPrintWriter(java.lang.String filePath, java.nio.charset.Charset charset)` Create a new `PrintWriter`, without automatic line flushing, writing to the specified file path and using the specified Charset.
    `static boolean` | `checkFlag(int value, int flag)` Indicates whether a byte-flag is set or not in a given value.
    `static <E> boolean` | `checkIndex(int index, java.util.List<E> list)` Indicates if a given index is within the list bounds.
    `static <T> boolean` | `checkIndex(int index, T[] array)` Returns true if a given index is within the array bounds.
    `static <T extends java.lang.Comparable<T>> java.util.Comparator<T>` | `createComparatorHandlingNullKeys(java.lang.Class<T> clazz)`
    `static boolean` | `createDirectories(java.lang.String path)` Creates the directory tree for the give full path (dir+filename)
    `static javax.xml.xpath.XPathFactory` | `createXPathFactory()` creates an XPathFactory and tries to handle issues with saxon.
    `static boolean` | `deleteDirectory(java.io.File directory)` Recursive function to delete the content of a given directory (including all its sub-directories.
    `static void` | `deleteDirectory(java.lang.String directory, boolean contentOnly)` Deletes the content of a given directory, and if requested, the directory itself.
    `static java.lang.String` | `deleteLastChar(java.lang.String string)` Deletes the last character of a given string.
    `static void` | `deleteLastChar(java.lang.StringBuilder sb)` Deletes the last character of a given StringBuilder object.
    `static java.lang.String` | `ensureLeadingSeparator(java.lang.String path, boolean forceForwardSlash)` Determines if a given path starts with a file name separator for the current platform.
    `static java.lang.String` | `ensureSeparator(java.lang.String path, boolean forceForwardSlash)` Determines if a given path ends with a file name separator for the current platform.
    `static java.lang.String` | `escapeToRTF(java.lang.String text, boolean convertLineBreaks, int lineBreakStyle, java.nio.charset.CharsetEncoder encoder)` Escapes a given string into RTF format.
    `static java.lang.String` | `escapeToXML(java.lang.String text, int quoteMode, boolean escapeGT, java.nio.charset.CharsetEncoder encoder)` Escapes a string for XML.
    `static java.lang.String` | `escapeWhitespaceForXML(java.lang.String text)` Escape newlines and whitespace so they survive roundtrip as an xml attribute \n= \r= =
    `static java.lang.String` | `expandPath(java.lang.String path, java.lang.String rootDir, java.lang.String inputRootDir)` Expand all supported variables and canonicalize (resolve ".." and ".") a path.
    `static int` | `fastParseInt(java.lang.String s)` Convert String to int .
    `static java.lang.String` | `fillInputRootDirectoryVariable(java.lang.String original, java.lang.String inputRootDir)` Replaces in a given original string, a potential variable INPUT_ROOT_DIRECTORY_VAR by a given root directory.
    `static java.lang.String` | `fillRootDirectoryVariable(java.lang.String original, java.lang.String rootDir)` Replaces in a given original string, a potential variable ROOT_DIRECTORY_VAR by a given root directory.
    `static java.lang.String` | `fillSystemEnvars(java.lang.String original)` Expands environment variables by replacing strings of the type ${varname} with their values as reported by the system.
    `static java.lang.String` | `fixFilename(java.lang.String fileName)` Replaces unsupported characters in a given short file name (no directory path) with underscore.
    `static java.lang.String` | `fixFilename(java.lang.String fileName, java.lang.String replacer)` Replaces unsupported characters in a given short file name (no directory path) with a given replacer.
    `static java.lang.String` | `fixPath(java.lang.String path)` Removes exceeding separators in a given path.
    `static java.lang.String` | `fixPath(java.lang.String path, boolean forceOsSeparators)` Removes exceeding separators in a given path.
    `static java.lang.String` | `formatDouble(java.lang.Double value)` Formats a double value so only the significant trailing zeros are displayed.
    `static <T> T` | `get(T[] array, int index)` Gets the element of an array for a given index.
    `static char` | `getCharAt(java.lang.String string, int pos)` Gets a character at a given position in a string.
    `static java.lang.String` | `getClassLocation(java.lang.Class<?> theClass)` Gets the directory location of a given class.
    `static java.lang.String` | `getDirectoryName(java.lang.String path)` Gets the directory name of a full path.
    `static java.lang.String` | `getExtension(java.lang.String path)` Gets the extension of a given path or filename.
    `static java.lang.String` | `getFilename(java.lang.String path, boolean keepExtension)` Gets the filename of a path.
    `static java.lang.String[]` | `getFilteredFiles(java.lang.String directory, java.lang.String suffix)` Return a list of files based on suffix (i.e, .xml, .html etc.)
    `static char` | `getLastChar(java.lang.String string)` Gets the last character of a given string.
    `static char` | `getLastChar(java.lang.StringBuilder sb)` Gets the last character of a given StringBuilder object.
    `static int` | `getLength(java.lang.String string)` Gets the length of a string, even a null one.
    `static Util.SUPPORTED_OS` | `getOS()` Get the operating system
    `static int` | `getPercentage(int part, int total)` Calculates safely a percentage.
    `static java.lang.String` | `getTempDirectory()` Gets the default system temporary directory to use for the current user.
    `static java.lang.String` | `getTextContent(org.w3c.dom.Node node)` Gets the text content of the first TEXT child of an element node.
    `static <K,V> V` | `getValue(java.util.Map<K,V> map, K key, V defaultValue)` Safely returns a value for a given key in a given map.
    `static java.lang.String` | `intToStr(int value)` Converts an integer value to a string.
    `static <E> boolean` | `isEmpty(java.util.List<E> e)` Indicates if a given list is null or empty.
    `static <K,V> boolean` | `isEmpty(java.util.Map<K,V> map)` Indicates if a given map is null or empty.
    `static boolean` | `isEmpty(java.lang.Object[] e)` Indicates if an array is null or empty.
    `static boolean` | `isEmpty(java.lang.String string)` Indicates if a given string is null or empty.
    `static boolean` | `isEmpty(java.lang.String string, boolean ignoreWS)` Indicates if a string is null or empty, optionally ignoring the white spaces.
    `static boolean` | `isEmpty(java.lang.StringBuilder sb)` Indicates if a StringBuilder object is null or empty.
    `static boolean` | `isNullOrEmpty(LocaleId locale)` Indicates if a locale id is null or empty.
    `static boolean` | `isOSCaseSensitive()` Indicates if the current OS is case-sensitive.
    `static boolean` | `isSameLanguage(java.lang.String lang1, java.lang.String lang2, boolean ignoreRegion)` Indicates if two language codes are 'the same'.
    `static boolean` | `isValidInXML(int ch)` Indicates if the given character is valid in XML.
    `static java.lang.String` | `longestCommonDir(boolean ignoreCase, java.lang.String... directories)` Gets the longest common path between directories on a given list.
    `static java.lang.String` | `longestCommonDir(java.lang.String currentDir, java.lang.String newDir, boolean ignoreCase)` Gets the longest common path between an existing current directory and a new one.
    `static java.lang.String` | `makeId(java.lang.String text)` Creates a string Identifier based on the hash code of the given text.
    `static java.lang.String` | `makeURIFromPath(java.lang.String pathOrUri)` Makes a URI string from a path.
    `static int` | `min(int... values)` Returns the smallest value in a given array of values.
    `static java.lang.String` | `normalizeNewlines(java.lang.String text)` Converts all \r\n and \r to linefeed (\n)
    `static int` | `normalizeRange(double low, double high, double value)` Given an integer range and a value normalize that value on a scale between 0 and 100.
    `static void` | `openURL(java.lang.String url)` Opens the specified page in a web browser (Java 1.5 compatible).
    `static void` | `openWikiTopic(java.lang.String topic)` Opens a given topic of the OkapiWiki.
    `static java.io.Reader` | `skipBOM(java.io.Reader r)` Given a Reader, discard any leading BOM.
    `static double` | `strToDouble(java.lang.String value, double doubleDefault)` Converts a string to a double.
    `static int` | `strToInt(java.lang.String value, int intDefault)` Converts a string to an integer.
    `static long` | `strToLong(java.lang.String value, long longDefault)` Converts a string to a long.
    `static java.net.URI` | `toURI(java.lang.String pathOrUri)` Creates a new URI object from a path or a URI string.
    `static java.net.URL` | `toURL(java.lang.String pathOrUri)` Creates a new URL object from a path or a URI string.
    `static java.lang.String` | `trimEnd(java.lang.String text, java.lang.String chars)` Removes from the end of a string any of the specified characters.
    `static java.lang.String` | `trimStart(java.lang.String text, java.lang.String chars)` Removes from the start of a string any of the specified characters.
    `static java.lang.String` | `unescapeWhitespaceForXML(java.lang.String text)`
    `static java.net.URL` | `URItoURL(java.net.URI uri)` Convert a URI to a URL.
    `static java.lang.String` | `URLDecodeUTF8(java.lang.String s)` Decodes a application/x-www-form-urlencoded string using UTF-8.
    `static java.lang.String` | `URLEncodeUTF8(java.lang.String s)` Translates a string into application/x-www-form-urlencoded format using UTF-8.
    `static java.net.URI` | `URLtoURI(java.net.URL url)` Convert a URL to a URI.
    `static boolean` | `validateVariables(java.lang.String text, boolean allowEnvar, boolean allowRootDir, boolean allowInputRootDir)` Check a piece of text to make sure that all contained variables (${foo}) are resolvable by the fill...() methods in this class.
    `static void` | `writeBOMIfNeeded(java.io.Writer writer, boolean bomOnUTF8, java.lang.String encoding)` Writes a Byte-Order-Mark if the encoding indicates it is needed.

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

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

- - ### Field Detail

    - #### ROOT_DIRECTORY_VAR

          public static final java.lang.String ROOT_DIRECTORY_VAR

      Name of the root directory variable.
      See Also:
        Constant Field Values

    - #### INPUT_ROOT_DIRECTORY_VAR

          public static final java.lang.String INPUT_ROOT_DIRECTORY_VAR

      Name of the input root directory variable.
      See Also:
        Constant Field Values

    - #### LINEBREAK_DOS

          public static final java.lang.String LINEBREAK_DOS

      Line-break string for DOS/Windows.
      See Also:
        Constant Field Values

    - #### LINEBREAK_UNIX

          public static final java.lang.String LINEBREAK_UNIX

      Line-break string for Unix/Linux
      See Also:
        Constant Field Values

    - #### LINEBREAK_MAC

          public static final java.lang.String LINEBREAK_MAC

      Line-break string for Macintosh
      See Also:
        Constant Field Values

    - #### RTF_STARTCODE

          public static final java.lang.String RTF_STARTCODE

      Default RTF style for starting an external code.
      See Also:
        Constant Field Values

    - #### RTF_ENDCODE

          public static final java.lang.String RTF_ENDCODE

      Default RTF style for ending an external code.
      See Also:
        Constant Field Values

    - #### RTF_STARTINLINE

          public static final java.lang.String RTF_STARTINLINE

      Default RTF style for starting an internal code.
      See Also:
        Constant Field Values

    - #### RTF_ENDINLINE

          public static final java.lang.String RTF_ENDINLINE

      Default RTF style for ending an internal code.
      See Also:
        Constant Field Values

    - #### RTF_STARTMARKER

          public static final java.lang.String RTF_STARTMARKER

      Default RTF style for starting an in-between source/target marker.
      See Also:
        Constant Field Values

    - #### RTF_MIDMARKER1

          public static final java.lang.String RTF_MIDMARKER1

      Default RTF style for the first half of a middle part of an in-between source/target marker.
      See Also:
        Constant Field Values

    - #### RTF_MIDMARKER2

          public static final java.lang.String RTF_MIDMARKER2

      Default RTF style for the second half of a middle part of an in-between source/target marker.
      See Also:
        Constant Field Values

    - #### RTF_ENDMARKER

          public static final java.lang.String RTF_ENDMARKER

      Default RTF style for ending an in-between source/target marker.
      See Also:
        Constant Field Values

    - #### MTFLAG

          public static final java.lang.String MTFLAG

      Shared flag indicating a translation that was generated using machine translation.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Util

          public Util()

  - ### Method Detail

    - #### normalizeNewlines

          public static java.lang.String normalizeNewlines(java.lang.String text)

      Converts all \r\n and \r to linefeed (\n)
      Parameters:
        `text` - the text to convert
      Returns:
        converted string

    - #### trimStart

          public static java.lang.String trimStart(java.lang.String text,
                                   java.lang.String chars)

      Removes from the start of a string any of the specified characters.
      Parameters:
        `text` - string to trim.
        `chars` - list of the characters to trim.
      Returns:
        The trimmed string.

    - #### trimEnd

          public static java.lang.String trimEnd(java.lang.String text,
                                 java.lang.String chars)

      Removes from the end of a string any of the specified characters.
      Parameters:
        `text` - string to trim.
        `chars` - list of the characters to trim.
      Returns:
        the trimmed string.

    - #### getDirectoryName

          public static java.lang.String getDirectoryName(java.lang.String path)

      Gets the directory name of a full path.
      Parameters:
        `path` - full path from where to extract the directory name. The path can be a URL path (e.g. "/C:/test/file.ext").
      Returns:
        The directory name (without the final separator), or an empty string if path is a filename.

    - #### ensureSeparator

          public static java.lang.String ensureSeparator(java.lang.String path,
                                         boolean forceForwardSlash)

      Determines if a given path ends with a file name separator for the current platform. If not, the file separator is appended to the path.
      Parameters:
        `path` - the given path.
        `forceForwardSlash` - true if the ending separator must be a forward slash.
      Returns:
        the given path ending with the file name separator.

    - #### ensureLeadingSeparator

          public static java.lang.String ensureLeadingSeparator(java.lang.String path,
                                                boolean forceForwardSlash)

      Determines if a given path starts with a file name separator for the current platform. If not, the file separator is prefixed to the path.
      Parameters:
        `path` - the given path.
        `forceForwardSlash` - true if the leading separator must be a forward slash.
      Returns:
        the given path starting with the file name separator.

    - #### fixFilename

          public static java.lang.String fixFilename(java.lang.String fileName,
                                     java.lang.String replacer)

      Replaces unsupported characters in a given short file name (no directory path) with a given replacer.
      Parameters:
        `fileName` - the given short file name
        `replacer` - the given replacer
      Returns:
        the given file name with fixed unsupported characters

    - #### fixPath

          public static java.lang.String fixPath(java.lang.String path)

      Removes exceeding separators in a given path. Normalizes the given path to contain OS-specific file separators.
      Parameters:
        `path` - the given path
      Returns:
        the fixed given path

    - #### fixPath

          public static java.lang.String fixPath(java.lang.String path,
                                 boolean forceOsSeparators)

      Removes exceeding separators in a given path. Optionally normalizes the given path to contain OS-specific file separators.
      Parameters:
        `path` - the given path
        `forceOsSeparators` - true to ensure the path contains only OS-specific separators
      Returns:
        the fixed given path

    - #### fixFilename

          public static java.lang.String fixFilename(java.lang.String fileName)

      Replaces unsupported characters in a given short file name (no directory path) with underscore.
      Parameters:
        `fileName` - the given short file name
      Returns:
        the given file name with fixed unsupported characters

    - #### buildPath

          public static java.lang.String buildPath(java.lang.String... parts)

      Builds a path from given parts. Path separators are normalized.
      Parameters:
        `parts` - parts of the path
      Returns:
        path containing the given parts separated with a file name separator for the current platform.

    - #### getFilteredFiles

          public static java.lang.String[] getFilteredFiles(java.lang.String directory,
                                            java.lang.String suffix)
                                                     throws java.net.URISyntaxException

      Return a list of files based on suffix (i.e, .xml, .html etc.)
      Parameters:
        `directory` - - directory where files are located
        `suffix` - - the sufix used to filter files
      Returns:
        - list of files matching the suffix
      Throws:
        `java.net.URISyntaxException` - if the syntax is not correct.

    - #### createDirectories

          public static boolean createDirectories(java.lang.String path)

      Creates the directory tree for the give full path (dir+filename)
      Parameters:
        `path` - directory to create and filename. If you want to pass only a directory name make sure it has a trailing separator (e.g. "c:\project\tmp\"). The path can be a URL path (e.g. "/C:/test/file.ext").
      Returns:
        true if one of more directories were created or if there was no directory to create, false otherwise (an error occurred)

    - #### escapeWhitespaceForXML

          public static java.lang.String escapeWhitespaceForXML(java.lang.String text)

      Escape newlines and whitespace so they survive roundtrip as an xml attribute \n= \r= =
      Parameters:
        `text` - - original text
      Returns:
        escaped string

    - #### unescapeWhitespaceForXML

          public static java.lang.String unescapeWhitespaceForXML(java.lang.String text)

    - #### escapeToXML

          public static java.lang.String escapeToXML(java.lang.String text,
                                     int quoteMode,
                                     boolean escapeGT,
                                     java.nio.charset.CharsetEncoder encoder)

      Escapes a string for XML.
      Parameters:
        `text` - string to escape.
        `quoteMode` - 0=no quote escaped, 1=apos and quot, 2=#39 and quot, and 3=quot only.
        `escapeGT` - true to always escape '>' to gt
        `encoder` - the character set encoder to use to detect un-supported character, or null to never escape normal characters.
      Returns:
        the escaped string.

    - #### escapeToRTF

          public static java.lang.String escapeToRTF(java.lang.String text,
                                     boolean convertLineBreaks,
                                     int lineBreakStyle,
                                     java.nio.charset.CharsetEncoder encoder)

      Escapes a given string into RTF format.
      Parameters:
        `text` - the string to convert.
        `convertLineBreaks` - Indicates if the line-breaks should be converted.
        `lineBreakStyle` - Type of line-break conversion. 0=do nothing special, 1=close then re-open as external, 2=close then re-open as internal.
        `encoder` - Encoder to use for the extended characters.
      Returns:
        The input string escaped to RTF.

    - #### deleteDirectory

          public static boolean deleteDirectory(java.io.File directory)

      Recursive function to delete the content of a given directory (including all its sub-directories. This does not delete the original parent directory.
      Parameters:
        `directory` - the directory of the content to delete.
      Returns:
        true if the content was deleted, false otherwise.

    - #### deleteDirectory

          public static void deleteDirectory(java.lang.String directory,
                             boolean contentOnly)

      Deletes the content of a given directory, and if requested, the directory itself. Sub-directories and their content are part of the deleted content.
      Parameters:
        `directory` - the path of the directory to delete
        `contentOnly` - indicates if the directory itself should be removed. If this flag is true, only the content is deleted.

    - #### getFilename

          public static java.lang.String getFilename(java.lang.String path,
                                     boolean keepExtension)

      Gets the filename of a path.
      Parameters:
        `path` - the path from where to get the filename. The path can be a URL path (e.g. "/C:/test/file.ext").
        `keepExtension` - true to keep the existing extension, false to remove it.
      Returns:
        the filename with or without extension.

    - #### getExtension

          public static java.lang.String getExtension(java.lang.String path)

      Gets the extension of a given path or filename.
      Parameters:
        `path` - the original path or filename.
      Returns:
        the last extension of the filename (including the period), or empty if there is no period in the filename. If the filename ends with a period, the return is a period. Never returns null.

    - #### makeURIFromPath

          public static java.lang.String makeURIFromPath(java.lang.String pathOrUri)

      Makes a URI string from a path. If the path itself can be recognized as a string URI already, it is passed unchanged. For example "C:\test" and "file:///C:/test" will both return "file:///C:/test" encoded as URI.
      Parameters:
        `pathOrUri` - the path to change to URI string.
      Returns:
        the URI string.
      Throws:
        `OkapiUnsupportedEncodingException` - if UTF-8 is not supported (can't happen).

    - #### toURI

          public static java.net.URI toURI(java.lang.String pathOrUri)

      Creates a new URI object from a path or a URI string.
      Parameters:
        `pathOrUri` - the path or URI string to use.
      Returns:
        the new URI object for the given path or URI string.

    - #### toURL

          public static java.net.URL toURL(java.lang.String pathOrUri)

      Creates a new URL object from a path or a URI string. This is a convenience wrapper to catch the various conversion exceptions.
      Parameters:
        `pathOrUri` - the path or URI string to use.
      Returns:
        the new URI object for the given path or URI string.

    - #### URLtoURI

          public static java.net.URI URLtoURI(java.net.URL url)

      Convert a URL to a URI. Convenience method to avoid catching `URISyntaxException` all over the place.
      Parameters:
        `url` - The URL to convert
      Returns:
        The new URI object for the given URL

    - #### URItoURL

          public static java.net.URL URItoURL(java.net.URI uri)

      Convert a URI to a URL. Convenience method to avoid catching `MalformedURLException`.
      Parameters:
        `uri` -
      Returns:

    - #### longestCommonDir

          public static java.lang.String longestCommonDir(java.lang.String currentDir,
                                          java.lang.String newDir,
                                          boolean ignoreCase)

      Gets the longest common path between an existing current directory and a new one.
      Parameters:
        `currentDir` - the current longest common path.
        `newDir` - the new directory to compare with.
        `ignoreCase` - true if the method should ignore cases differences.
      Returns:
        the longest sub-directory that is common to both directories. This can be a null if the current directory is null, or empty if there is no common path.

    - #### longestCommonDir

          public static java.lang.String longestCommonDir(boolean ignoreCase,
                                          java.lang.String... directories)

      Gets the longest common path between directories on a given list.
      Parameters:
        `ignoreCase` - if the method should ignore cases differences.
        `directories` - the given list of directories.
      Returns:
        the longest sub-directory that is common to all directories. This can be a null or empty string.

    - #### isOSCaseSensitive

          public static boolean isOSCaseSensitive()

      Indicates if the current OS is case-sensitive.
      Returns:
        true if the current OS is case-sensitive, false if otherwise.

    - #### writeBOMIfNeeded

          public static void writeBOMIfNeeded(java.io.Writer writer,
                              boolean bomOnUTF8,
                              java.lang.String encoding)

      Writes a Byte-Order-Mark if the encoding indicates it is needed. This methods must be the first call after opening the writer.
      Parameters:
        `writer` - writer where to output the BOM.
        `bomOnUTF8` - indicates if we should use a BOM on UTF-8 files.
        `encoding` - encoding of the output.
      Throws:
        `OkapiIOException` - if anything went wrong with the writing.

    - #### getTempDirectory

          public static java.lang.String getTempDirectory()

      Gets the default system temporary directory to use for the current user. The directory path returned has never a trailing separator.
      Returns:
        The directory path of the temporary directory to use, without trailing separator.

    - #### getTextContent

          public static java.lang.String getTextContent(org.w3c.dom.Node node)

      Gets the text content of the first TEXT child of an element node. This is to use instead of node.getTextContent() which does not work with some Macintosh Java VMs. Note this work-around get only the first TEXT node.
      Parameters:
        `node` - the container element.
      Returns:
        the text of the first TEXT child node.

    - #### getPercentage

          public static int getPercentage(int part,
                          int total)

      Calculates safely a percentage. If the total is 0, the methods return 1.
      Parameters:
        `part` - the part of the total.
        `total` - the total.
      Returns:
        the percentage of part in total.

    - #### makeId

          public static java.lang.String makeId(java.lang.String text)

      Creates a string Identifier based on the hash code of the given text.
      Parameters:
        `text` - the text to make an ID for.
      Returns:
        The string identifier for the given text.

    - #### isSameLanguage

          public static boolean isSameLanguage(java.lang.String lang1,
                               java.lang.String lang2,
                               boolean ignoreRegion)

      Indicates if two language codes are 'the same'. The comparison ignores case differences, and if the parameter ignoreRegion is true, any part after the first '-' is also ignored. Note that the character '_' is treated like a character '-'.
      Parameters:
        `lang1` - first language code to compare.
        `lang2` - second language code to compare.
        `ignoreRegion` - True to ignore any part after the first separator, false to take it into account.
      Returns:
        true if, according the given options, the two language codes are the same. False otherwise.

    - #### isEmpty

          public static boolean isEmpty(java.lang.String string)

      Indicates if a given string is null or empty.
      Parameters:
        `string` - the string to check.
      Returns:
        true if the given string is null or empty.

    - #### isNullOrEmpty

          public static boolean isNullOrEmpty(LocaleId locale)

      Indicates if a locale id is null or empty.
      Parameters:
        `locale` - the locale id to examine.
      Returns:
        true if the given locale id is null or empty, false otherwise.

    - #### isEmpty

          public static boolean isEmpty(java.lang.String string,
                        boolean ignoreWS)

      Indicates if a string is null or empty, optionally ignoring the white spaces.
      Parameters:
        `string` - the string to examine.
        `ignoreWS` - true to ignore white spaces.
      Returns:
        true if the given string is null, or empty. The argument ignoreWS is true a string with only white spaces is concidered empty.

    - #### isEmpty

          public static boolean isEmpty(java.lang.StringBuilder sb)

      Indicates if a StringBuilder object is null or empty.
      Parameters:
        `sb` - the object to examine.
      Returns:
        true if the given object is null or empty.

    - #### isEmpty

          public static <E> boolean isEmpty(java.util.List<E> e)

      Indicates if a given list is null or empty.
      Type Parameters:
        `E` - the type of the elements in the list.
      Parameters:
        `e` - the list to examine.
      Returns:
        true if the list is null or empty.

    - #### isEmpty

          public static <K,V> boolean isEmpty(java.util.Map<K,V> map)

      Indicates if a given map is null or empty.
      Type Parameters:
        `K` - the type of the map's keys.
        `V` - the type of the map's values.
      Parameters:
        `map` - the map to examine.
      Returns:
        true if the map is null or empty,

    - #### isEmpty

          public static boolean isEmpty(java.lang.Object[] e)

      Indicates if an array is null or empty.
      Parameters:
        `e` - the array to examine.
      Returns:
        true if the given array is null or empty.

    - #### getLength

          public static int getLength(java.lang.String string)

      Gets the length of a string, even a null one.
      Parameters:
        `string` - the string to examine.
      Returns:
        the length of the given string, 0 if the string is null.

    - #### getCharAt

          public static char getCharAt(java.lang.String string,
                       int pos)

      Gets a character at a given position in a string. The string can be null and the position can be beyond the last character.
      Parameters:
        `string` - the string to examine.
        `pos` - the position of the character to retrieve.
      Returns:
        the character at the given position, or '\0' if the string is null or if the position is beyond the length of the string.

    - #### getLastChar

          public static char getLastChar(java.lang.String string)

      Gets the last character of a given string. The string can be null or empty.
      Parameters:
        `string` - the string to examine.
      Returns:
        the last character of the given string, or '\0' if the string is null or empty.

    - #### deleteLastChar

          public static java.lang.String deleteLastChar(java.lang.String string)

      Deletes the last character of a given string. The string can be null or empty.
      Parameters:
        `string` - the string where to remove the character.
      Returns:
        a new string where the last character has been removed, or an empty string if the given string was null or empty.

    - #### getLastChar

          public static char getLastChar(java.lang.StringBuilder sb)

      Gets the last character of a given StringBuilder object. The object can be null or empty.
      Parameters:
        `sb` - the StringBuilder object to examine.
      Returns:
        the last character of the given StringBuilder object, or '\0' if the object is null or empty.

    - #### deleteLastChar

          public static void deleteLastChar(java.lang.StringBuilder sb)

      Deletes the last character of a given StringBuilder object. If the object is null or empty no character are removed.
      Parameters:
        `sb` - the StringBuilder object where to remove the character.

    - #### checkIndex

          public static <E> boolean checkIndex(int index,
                               java.util.List<E> list)

      Indicates if a given index is within the list bounds.
      Type Parameters:
        `E` - the type of the list's elements.
      Parameters:
        `index` - the given index.
        `list` - the given list.
      Returns:
        true if a given index is within the list bounds.

    - #### intToStr

          public static java.lang.String intToStr(int value)

      Converts an integer value to a string. This method simply calls `String.valueOf(intValue);`.
      Parameters:
        `value` - the value to convert.
      Returns:
        the string representation of the given value.

    - #### strToInt

          public static int strToInt(java.lang.String value,
                     int intDefault)

      Converts a string to an integer. If the conversion fails the method returns the given default value.
      Parameters:
        `value` - the string to convert.
        `intDefault` - the default value to use if the conversion fails.
      Returns:
        the integer value of the string, or the provided default value if the conversion failed.

    - #### fastParseInt

          public static int fastParseInt(java.lang.String s)

      Convert String to int . Almost 3x faster than Integer.valueOf()
      Parameters:
        `s` - - string to be converted to int
      Returns:
        int represented by string
      Throws:
        `java.lang.NumberFormatException` - if the `String` does not represent a number.

    - #### strToLong

          public static long strToLong(java.lang.String value,
                       long longDefault)

      Converts a string to a long. If the conversion fails the method returns the given default value.
      Parameters:
        `value` - the string to convert.
        `longDefault` - the default value to use if the conversion fails.
      Returns:
        the long value of the string, or the provided default value if the conversion failed.

    - #### strToDouble

          public static double strToDouble(java.lang.String value,
                           double doubleDefault)

      Converts a string to a double. If the conversion fails the method returns the given default value.
      Parameters:
        `value` - the string to convert.
        `doubleDefault` - the default value to use if the conversion fails.
      Returns:
        the double value of the string, or the provided default value if the conversion failed.

    - #### get

          public static <T> T get(T[] array,
                  int index)

      Gets the element of an array for a given index. the method returns null if the index is out of bounds.
      Type Parameters:
        `T` - the type of the array's elements.
      Parameters:
        `array` - the array where to lookup the element.
        `index` - the index.
      Returns:
        the element of the array for the given index, or null if the index is out of bounds, or if the element is null.

    - #### checkIndex

          public static <T> boolean checkIndex(int index,
                               T[] array)

      Returns true if a given index is within the array bounds.
      Type Parameters:
        `T` - the type of the array's elements.
      Parameters:
        `index` - the given index.
        `array` - the given list.
      Returns:
        true if a given index is within the array bounds.

    - #### checkFlag

          public static boolean checkFlag(int value,
                          int flag)

      Indicates whether a byte-flag is set or not in a given value.
      Parameters:
        `value` - the value to check.
        `flag` - the flag to look for.
      Returns:
        true if the flag is set, false if it is not.

    - #### getOS

          public static Util.SUPPORTED_OS getOS()

      Get the operating system
      Returns:
        one of WINDOWS, MAC or LINUX

    - #### openURL

          public static void openURL(java.lang.String url)

      Opens the specified page in a web browser (Java 1.5 compatible).

      This is based on the public domain class BareBonesBrowserLaunch from Dem Pilafian at (www.centerkey.com/java/browser)

      Parameters:
        `url` - the URL of the page to open.

    - #### openWikiTopic

          public static void openWikiTopic(java.lang.String topic)

      Opens a given topic of the OkapiWiki.
      Parameters:
        `topic` - the title of the topic/page.

    - #### getClassLocation

          public static java.lang.String getClassLocation(java.lang.Class<?> theClass)

      Gets the directory location of a given class. The value returned can be the directory where the .class file is located, or, if the class in a JAR file, the directory where the .jar file is located.
      Parameters:
        `theClass` - the class to query.
      Returns:
        the directory location of the given class, or null if an error occurs.

    - #### fillRootDirectoryVariable

          public static java.lang.String fillRootDirectoryVariable(java.lang.String original,
                                                   java.lang.String rootDir)

      Replaces in a given original string, a potential variable ROOT_DIRECTORY_VAR by a given root directory.
      Parameters:
        `original` - the original string where to perform the replacement.
        `rootDir` - the root directory. If null it will be automatically set to the user home directory.
      Returns:
        the original string with ROOT_DIRECTORY_VAR replaced if it was there.

    - #### fillInputRootDirectoryVariable

          public static java.lang.String fillInputRootDirectoryVariable(java.lang.String original,
                                                        java.lang.String inputRootDir)

      Replaces in a given original string, a potential variable INPUT_ROOT_DIRECTORY_VAR by a given root directory.
      Parameters:
        `original` - the original string where to perform the replacement.
        `inputRootDir` - the input root directory. If null it will be automatically set to an empty string.
      Returns:
        the original string with INPUT_ROOT_DIRECTORY_VAR replaced if it was there.

    - #### fillSystemEnvars

          public static java.lang.String fillSystemEnvars(java.lang.String original)

      Expands environment variables by replacing strings of the type ${varname} with their values as reported by the system.
      Parameters:
        `original` - The original string in which to perform the replacement
      Returns:
        The original string with all environment variables expanded

    - #### validateVariables

          public static boolean validateVariables(java.lang.String text,
                                  boolean allowEnvar,
                                  boolean allowRootDir,
                                  boolean allowInputRootDir)

      Check a piece of text to make sure that all contained variables (${foo}) are resolvable by the fill...() methods in this class.
      Parameters:
        `text` - The text to check
        `allowEnvar` - Whether or not to allow system environment variables
        `allowRootDir` - Whether or not to allow ${rootDir}
        `allowInputRootDir` - Whether or not to allow ${inputRootDir}
      Returns:
        Whether or not the input text's variables are valid

    - #### expandPath

          public static java.lang.String expandPath(java.lang.String path,
                                    java.lang.String rootDir,
                                    java.lang.String inputRootDir)
                                             throws java.io.IOException

      Expand all supported variables and canonicalize (resolve ".." and ".") a path. If the input path has no variables, it is returned unchanged. rootDir and inputRootDir can be null.
      Parameters:
        `path` - The path to expand
        `rootDir` - The directory to expand ${rootDir} into
        `inputRootDir` - The directory to expand ${inputRootDir} into
      Returns:
        The expanded path
      Throws:
        `java.io.IOException` - If canonicalizing fails

    - #### min

          public static int min(int... values)

      Returns the smallest value in a given array of values.
      Parameters:
        `values` - the given array
      Returns:
        the smallest value in the array

    - #### getValue

          public static <K,V> V getValue(java.util.Map<K,V> map,
                         K key,
                         V defaultValue)

      Safely returns a value for a given key in a given map.
      Type Parameters:
        `V` - the type of keys maintained by the given map
        `K` - the type of mapped values of the given map
      Parameters:
        `map` - the given map
        `key` - the key whose associated value is to be returned
        `defaultValue` - the default value to be returned if the key is not found
      Returns:
        the value to which the specified key is mapped, or defaultValue if the given map contains no mapping for the given key

    - #### normalizeRange

          public static int normalizeRange(double low,
                           double high,
                           double value)

      Given an integer range and a value normalize that value on a scale between 0 and 100.
      Parameters:
        `low` - - lowest value of the range
        `high` - - highest value of the range
        `value` - - the value that needs to be mapped to 0-100
      Returns:
        mapped value, a number between 0 and 100

    - #### formatDouble

          public static java.lang.String formatDouble(java.lang.Double value)

      Formats a double value so only the significant trailing zeros are displayed. Removes the decimal period if there are no significant decimal digits.
      Parameters:
        `value` - the double value to format (can be null).
      Returns:
        the formatted value or an empty string.

    - #### isValidInXML

          public static boolean isValidInXML(int ch)

      Indicates if the given character is valid in XML. See http://www.w3.org/TR/xml/#charsets for details.
      Parameters:
        `ch` - the character to test.
      Returns:
        true if the given character is valid in XML, false otherwise.

    - #### URLDecodeUTF8

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

      Decodes a application/x-www-form-urlencoded string using UTF-8. This wraps a call to `URLDecoder.decode(String, String)`, passing UTF-8 as the argument and wrapping the exception as an `IllegalStateException`. This exists because URLDecoder does not offer a signature that takes a `Charset`.
      Parameters:
        `s` - the String to decode
      Returns:
        the newly decoded String
      Throws:
        `java.lang.IllegalStateException` - if UTF-8 isn't recognized as a valid encoding, which should never happen.

    - #### URLEncodeUTF8

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

      Translates a string into application/x-www-form-urlencoded format using UTF-8. This wraps a call to `URLEncoder.encode(String, String)`, passing UTF-8 as the argument and wrapping the exception as an `IllegalStateException`. This exists because URLEncoder does not offer a signature that takes a `Charset`.
      Parameters:
        `s` - the String to be translated
      Returns:
        the translated String
      Throws:
        `java.lang.IllegalStateException` - if UTF-8 isn't recognized as a valid encoding, which should never happen.

    - #### charsetPrintWriter

          public static java.io.PrintWriter charsetPrintWriter(java.lang.String filePath,
                                               java.nio.charset.Charset charset)
                                                        throws java.io.FileNotFoundException

      Create a new `PrintWriter`, without automatic line flushing, writing to the specified file path and using the specified Charset. PrintWriter doesn't provide this signature and requires a charset name be passed instead, which requires additional exception handling.
      Parameters:
        `filePath` - the file to use as the destination of this writer.
        `charset` - charset to use when writing to the file
      Returns:
        new PrintWriter instance
      Throws:
        `java.io.FileNotFoundException` - if the given string does not denote an existing, writable regular file and a new regular file of that name can't be created.

    - #### skipBOM

          public static java.io.Reader skipBOM(java.io.Reader r)
                                        throws java.io.IOException

      Given a Reader, discard any leading BOM.
      Parameters:
        `r` - the reader.
      Returns:
        a Reader instance representing the remaining content. This may not be the same Reader instance that was passed in.
      Throws:
        `java.io.IOException` - if anything goes wrong when reading.

    - #### createComparatorHandlingNullKeys

          public static <T extends java.lang.Comparable<T>> java.util.Comparator<T> createComparatorHandlingNullKeys(java.lang.Class<T> clazz)

      Type Parameters:
        `T` - the type of the class.
      Parameters:
        `clazz` - the class.
      Returns:
        a comparator for `TreeMap` that accepts null keys.

    - #### createXPathFactory

          public static javax.xml.xpath.XPathFactory createXPathFactory()

      creates an XPathFactory and tries to handle issues with saxon.
      Returns:
        the `XPathFactory` created.
      See Also:
        https://saxonica.plan.io/issues/1944, http://sourceforge.net/p/saxon/mailman/message/33221102/