var lib = window.lib || {};


lib.StringUtils = {

    //*********************   methods ***********************

    /**
     * Removes the outermost quotes (pair of ' or ") from the string.
     *
     * @return If <code>s</code> contains no quotes as the first and last character, it is returned unchanged.
     */
    removeQuotes: function (s) {
    },

    /**
     * Checks if the string is a digit. (0-9)
     *
     * @usage if (StringUtils.isDigit(myChar)) {...}
     * @param x; the string to test (only 1 character)
     * @return true if the string is a digit, otherwise false
     */
    isDigit: function (x) {
        if ((x.length == 0) || isNaN(x) || (x<0 || x>9)){
            return false;
        }
        return true;
    },

    /**
     * Checks if the string is a letter.
     *
     * @usage if (StringUtils.isAlpha(myChar)) {...}
     * @param x; the string to test (only 1 character)
     // ---------------------------------------------------------------------------------------
     // ---------------------------------------------------------------------------------------
     // ---------------------------------------------------------------------------------------
     * @param bUnderscore: Boolean, optional; default:false; if true, the returns true also for the the underscore "_": function
     // ---------------------------------------------------------------------------------------
     // ---------------------------------------------------------------------------------------
     // ---------------------------------------------------------------------------------------
     * @return true if the string is an alpha character A-Za-z. If the parameter bUnderscore is true, and the String is the underscore "_", the returns true, too.: function
     */
    isAlpha: function (x, bUnderscore) {
        var ascii = x.charCodeAt(0);
        // check if x is an undersore
        if (ascii == 95 && bUnderscore == true)
            return true;
        // check if x is an alpha character
        else if ((ascii > 64 && ascii < 91) || (ascii > 96 && ascii < 123))
            return true;
        return false;
    },

    /**
     * Checks if the string is an alphanumerical character.
     *
     * @usage if (StringUtils.isAlNum(myChar)) {...}
     * @param x; the string to test (only 1 character)
     * @param bUnderscore, optional; default:false; if true, the returns true also for the the underscore "_": function
     * @return true, if the the string is the character 0-9a-zA-Z or (if bUnderscore is true), the underscore "_"
     */
    isAlNum: function (x, bUnderscore) {
    },

    /**
     * Converts common characters to their HTML character entities.
     *
     * @usage var sHTML = StringUtils.htmlEncode(myString);
     * @param x; the string
     * @return the HTML-encoded string.
     */
    htmlEncode: function (x) {
    },

    /**
     * Compares a string to a given list of srings
     *
     * @usage if (StringUtils.mEquals(myString,"a","aa","abc")) {...}
     * @param s The string which is being compared
     * @param compareStrings A variable list of compare strings
     * @return true, if the string matches any of the compare strings (logical or)
     */
    mEquals: function (s) {
    },

    /**
     * Checks if a string starts with the compare string.
     *
     * @usage if (StringUtils.startsWith("hello world", "hel")) {...}
     * @param s The string which is being checked
     * @param compareString The compare string
     * @return true, if the string <code>s</code> starts with the string <code>compareString</code>.
     */
    startsWith: function (s, compareString) {
        if (s.indexOf(compareString) == 0)
            return true;
        return false;
    },

    /**
     * Checks, if s starts with at least one of the compare strings
     *
     * @usage if (StringUtils.mStartsWith("hello world","hal","hel","hello")) {...}
     * @param s The string wich is being checked
     * @param compareString A variable list of compare strings
     * @return true, if the string starts with at least one of the compare strings
     */
    mStartsWith: function (s) {
    },

    /**
     * Checks if a string ends with the compare string.
     *
     * @usage if (StringUtils.endsWith("hello world", "hel")) {...}
     * @param s The string which is being checked
     * @param compareString The compare string
     * @return true, if the string <code>s</code> ends with the string <code>compareString</code>.
     */
    endsWith: function (s, compareString) {
    },

    /**
     * Checks, if s ends with at least one of the compare strings
     *
     * @usage if (StringUtils.mEndsWith("hello world","hal","hel","hello")) {...}
     * @param s The string wich is being checked
     * @param compareString A variable list of compare strings
     * @return true, if the string ends with at least one of the compare strings
     */
    mEndsWith: function (s) {
    },

    /**
     * Repeats a string "count" times.
     *
     * @usage var result = StringUtils.repeat("hello", 3); // "hellohellohello"
     * @param s The string wich is repeated.
     * @param count How often should the string be repeated. If value <= 0, the empty string is returned.
     * @return The repeated string
     */
    repeat: function (x, count) {
    },

    /**
     * Returns a string where every occurrence of toReplace is being replaced by replaceBy.
     *
     * @usage console.log(StringUtils.replace("hello world", "o", "xx")); // outputs "hellxx wxxrld"
     * @param s The string
     * @param toReplace Substring to be replaced. If <code>toReplace</code> is the empty string, <code>replaceBy</code> is inserted after every character.
     * @param replaceBy The replacement string
     * @return the string with the replacements done
     */
    replace: function (s, toReplace, replaceBy) {
    },

    /**
     * Returns a string where all occurruences of the compare strings in the variable parameter list
     * are replaced by the last string in the parameter list.
     *
     * @usage console.log(StringUtils.mReplace("hello world","o","l","xx")); // outputs "hexxxxxx wxxrxxd"
     * @param x; the string
     * @param variable parameter list of n strings
     * @param strings 1 to (n-1): all strings to be replaced
     * @param string n: replacement string
     * @return
     */
    mReplace: function (x) {
    },

    /**
     * Inserts at the beginning of this the character character until the string has the length of len.
     * If the original string is longer than len, no characters are inserted but the string is not truncated.
     *
     * @usage
     *        console.log(StringUtils.lead("hello",8," ")); // outputs "   hello"
     *        console.log(StringUtils.lead("hello",3," ")); // outputs "hello"
     * @param s The string
     * @param len Desired length of the string after inserting of leading characters character
     * @param character Character to be inserted (must be a string with length of 1)
     * @return the new string with the inserted characters
     */
    lead: function (s, len, character) {
    },

    /**
     * Appends at the beginning of this the character character until the string has the length of len.
     * If the original string is longer than len, no characters are appended but the string is not truncated.
     *
     * @usage
     *        console.log(StringUtils.trail("hello",8,".")); // outputs "hello..."
     *        console.log(StringUtils.trail("hello",3,".")); // outputs "hello"
     * @param s The string
     * @param len Desired length of the string after appending of trailing characters character
     * @param character Character to be appended (must be a string with length=1)
     * @return the new string with the appended characters
     */
    trail: function (s, len, character) {
    },

    /**
     * Checks if the string contains only whitespace.
     *
     * @usage console.log(StringUtils.isWhite("  \t  ")); // outputs true
     * @param s The string
     * @return true if the string contains only whitespace.
     */
    isWhite: function (s) {
    },

    /**
     * Returns the number of occurences of compareString in this.
     *
     * @usage console.log(StringUtils.numberOf("hello world","l")); // outputs 3
     * @param s The string
     * @param compareString The string whose occurrence has to be counted
     * @return the number of occurences of compareString in this.
     */
    numberOf: function (s, compareString, offset, count) {
    },

    /**
     * Replaces nCount occurrences of the string sFrom by the replacement string sTo.
     *
     * @usage
     *        console.log(StringUtils.replaceNum("hello world","l","-",1); // outputs "he-lo world"
     *        console.log(StringUtils.replaceNum("hello world","l","-",0); // outputs "hello world"
     * @param x; the string
     * @param sFrom; string to be replaced
     * @param sTo; replacement string
     * @param nCount; number of desired replacements; for 0 or null or undefined, nothing is replaced
     * @return the string with the replacemenst applied
     */
    replaceNum: function (x, sFrom, sTo, nCount) {
    },

    /**
     * Removes one ore more occurrences of the string toRemove from the beginning and/or end of this.
     *
     * @usage
     *        console.log(StringUtils.trim("aabbccddccccbba","a"));                // bbccddccccbb
     *        console.log(StringUtils.trim("aabbccddccccbba","a",true,false));    // bbccddccccbba
     *        console.log(StringUtils.trim("aabbccddccccbba","a",false,true));    // bbccddccccbb
     *        console.log(StringUtils.trim("aabbccddccccbba","a",false,false));    // aabbccddccccbba
     * @param s The string
     * @param toRemove String to be removed
     * @param trimLeading If true, occurrences of toRemove are removed from the beginning of the string
     * @param trimTrailing Iftrue, occurrences of toRemove are removed from the end of the string
     * @return the trimmed string
     */
    trim: function (s, toRemove, trimLeading, trimTrailing) {
    },

    /**
     * Like StringUtils.trim but more compare strings can be specified in an array.
     *
     * @usage
     *        console.log(StringUtils.mTrim("aabbabccddccccbba",["a"])); // bbccddccccbb
     *        console.log(StringUtils.mTrim("aabbabccddccccbba",["a","b"])); // ccddcccc
     *        console.log(StringUtils.mTrim("aabbabccddccccbba",["a","c"],true,true)); // bbccddccccbb
     * @param s The string
     * @param stringsToRemove Array of compare strings which will all be removed from beginning/end of the string
     * @param trimLeading If true, remove from the beginning of the string
     * @param trimTrailing If true, remove from the end of the string
     */
    mTrim: function (s, stringsToRemove, trimLeading, trimTrailing) {
    },

    /**
     * Removes all of the following characters/string from the beginning/end of the string: " ","\t","\n","\r"
     *
     * @usage console.log(StringUtils.trimWhite("  hello \t ")); // outputs "hello"
     * @param s The string
     * @param trimLeading If true, remove from the beginning of the string
     * @param trimTrailing If true, remove from the end of the string
     * @return the trimmed string
     */
    trimWhite: function (s, trimLeading, trimTrailing) {
    },

    /**
     * Removes all of the following characters/string from the beginning/end of the string: " ","\t","\n","\r","<br>","&nbsp;"
     *
     * @usage console.log(StringUtils.trimHtmlWhite("  hello <br>&nbsp; ")); // outputs "hello"
     * @param s; the string
     * @param trimLeading; optional, default:true; if true, remove from the beginning of the string
     * @param trimTrailing; optional, default:true; if true, remove from the end of the string
     * @return the trimmed string
     */
    trimHtmlWhite: function (s, trimLeading, trimTrailing) {
    },

    /**
     * Converts the following special charactes into their Escape-Sequences.
     *
     *    <p>\\    will be converted to \\\\ </p>
     *    <p>\'    will be converted to \\\'</p>
     *    <p>\"    will be converted to \\\"</p>
     *    <p>\n    will be converted to \\n</p>
     *    <p>\r    will be converted to \\r</p>
     *    <p>\t    will be converted to \\t</p>
     *    <p>\b    will be converted to \\b</p>
     *    <p>\f    will be converted to \\f</p>
     *
     * @usage StringUtils.escapeCharSequences(myString)
     * @param s; the string
     * @return the converted string
     */
    escapeCharSequences: function (s) {
    },

    /**
     * Make a string's first character uppercase
     *
     * @usage StringUtils.toUpperCaseFirst(myString)
     * @param x; the string
     * @return the converted string
     */
    toUpperCaseFirst: function (s) {
    }
}