/**
 * Ytils JS Framework
 * string
 *
 * Ytils WebToolBox.
 *
 * Copyright (c) 2011 Kim Schneider, SIT - Schneider Internet Technologies.
 * The Ytils framework is a collection of PHP- and JavaScript utility- and widget-classes written by Kim Schneider.
 *
 * The Ytils WebToolBox is published under the GPL v3-licence. See LICENCE.txt for the licence-text.
 * The official source of the Ytils project is http://www.ytils.com.
 * The official website of SIT - Schneider Internet Technologies is http://www.schneidersit.de.
 *
 * Kiel, Germany, 2011-08-10.
 *
 * Notice:
 * This is partly based on the php.js-collection, so please notice the
 * following original copyright information:
 *
 * > More info at: http://kevin.vanzonneveld.net/techblog/category/php2js
 * >
 * > php.js is copyright 2008 Kevin van Zonneveld.
 * >
 * > Portions copyright Ates Goral (http://magnetiq.com), Legaev Andrey,
 * > _argos, Jonas Raoni Soares Silva (http://www.jsfromhell.com),
 * > Webtoolkit.info (http://www.webtoolkit.info/), Carlos R. L. Rodrigues, Ash
 * > Searle (http://hexmen.com/blog/), Tyler Akins (http://rumkin.com), mdsjack
 * > (http://www.mdsjack.bo.it), Alexander Ermolaev
 * > (http://snippets.dzone.com/user/AlexanderErmolaev), Andrea Giammarchi
 * > (http://webreflection.blogspot.com), Bayron Guevara, Cord, David, Karol
 * > Kowalski, Leslie Hoare, Lincoln Ramsay, Mick@el, Nick Callen, Peter-Paul
 * > Koch (http://www.quirksmode.org/js/beat.html), Philippe Baumann, Steve
 * > Clay, booeyOH
 *
 * @category  YTILS
 * @package   util.js.ytils.com
 * @copyright Copyright (c) 2010 Schneider IT-Services (http://www.schneider.ws)
 * @author    Kim Schneider
 * @license   http://ytils.schneider.ws/licence/
 * @version   0.1.0.1
 */

/*global YTILS */
/*jslint browser: true */
/*jslint strict: true */
/*jslint unparam: false */
/*jslint forin: true */
/*jslint white: true */
/*jslint plusplus: true */
(function(){

"use strict";

if (typeof YTILS.util === "undefined" || !YTILS.util)
{
  YTILS.util = {};
}

YTILS.util.string =
{
  /**
   * Compares the string a with string b.
   *
   * @param mixed a
   * @param mixed b
   * @return Boolean
   */
  equals: function(a, b)
  {
    return a.toString() === b.toString();
  },

  /**
   * Compares the string a with string b. Works case insensitive.
   *
   * @param mixed a
   * @param mixed b
   * @return Boolean
   */
  equalsCI: function(a, b)
  {
    return a.toString().toLocaleLowerCase() === b.toString().toLocaleLowerCase();
  },

  /**
   * Trims string val on the left.
   *
   * @param val
   * @return String
   */
  trimLeft: function(val)
  {
    return val.toString().replace(/^\s+/, "");
  },

  /**
   * Trims string val on the right.
   *
   * @param val
   * @return String
   */
  trimRight: function(val)
  {
    return val.toString().replace(/\s+$/, "");
  },

  /**
   * Trims string val.
   *
   * @param val
   * @return String
   */
  trim: function(val)
  {
    return YTILS.util.string.trimRight(YTILS.util.string.trimLeft(val));
  },

  /**
   * Removes all white-spaces on the left and right sides
   * and additionally removes multiple white-spaces within the string.
   *
   * @param val
   * @return String
   */
  removeMultipleWhiteSpaces: function(val)
  {
    return val.toString().replace(/\s+/g, " ").replace(/\s+$/, "").replace(/^\s+/, "");
  },

  /**
   * Removes all whitespaces.
   *
   * @param val
   * @return String
   */
  removeWhiteSpaces: function(val)
  {
    return val.toString().replace(/\s+/g, "");
  },

  /**
   * Returns true, if the param can be found within the string.
   * The second parameter is optional. If set true, the check
   * will be case insensitive.
   *
   * @param val
   * @param String needle: The string to search for.
   * @param Boolean ci Optional param to run the check case-insensitive. Defaults to false.
   * @return Boolean
   */
  contains: function(val, needle)
  {
    var
    ci,
    theArgs = arguments;

    needle = needle.toString();
    if (theArgs.length > 2)
    {
      ci = theArgs[2];
    }

    if (theArgs[2])
    {
      needle = needle.toLowerCase();
    }

    return val.toString().indexOf(needle) !== -1;
  },

  /**
   * Returns true if the string starts with needle. Pass a boolean true as second parameter
   * if you want to work case insensitive.
   *
   * @param val
   * @param String needle: The string to search for.
   * @param Boolean ci Optional param to run the check case-insensitive. Defaults to false.
   * @return Boolean
   */
  startsWith: function(val, needle)
  {
    var
    theArgs = arguments,
    check = val.toString(),
    sub = check.toString().substr(0, needle.length);

    if (theArgs[2])
    {
      check = check.toLowerCase();
      sub = sub.toLowerCase();
    }

    return (sub === needle);
  },

  /**
   * Returns true if the string ends with needle. Pass a boolean true as second parameter
   * if you want to work case insensitive.
   *
   * @param String needle: The string to search for.
   * @param Boolean ci Optional param to run the check case-insensitive. Defaults to false.
   * @return Boolean
   */
  endsWith: function(val, needle)
  {
    var theArgs = arguments,
        check = val.toString(),
        sub = check.substr((val.length - needle.length), needle.length);

    if (theArgs[1])
    {
      check = check.toLowerCase();
      sub = sub.toLowerCase();
    }

    return (sub === needle);
  },

  /**
   * Returns the string starting with a capital letter at the very beginning of the string.
   * Notice, that if the first character is not a letter (for example white-space or a number)
   * this will not cause a change
   *
   * @method String.prototype.md5()
   * @access public
   * @return String
   */
  ucFirst: function(val)
  {
    return val.toString().charAt(0).toUpperCase() + val.toString().substr(1);
  },

  /**
   * Calculates the md5-hash for a string message.
   *
   * @param val
   * @return String
   */
  md5: function(val)
  {
    return YTILS.util.hash.md5(val.toString());
  },

  /**
   * Gives back a string with most important HTML-entities for the use in european projects.
   * this is somehow a light-version of PHPs htmlentities().
   *
   * @param val
   * @return String
   */
  toEntity: function(val, quoteStyle)
  {
    var
    hashMap = {},
    symbol = '',
    temp = '',
    entity = '';

    temp = val.toString();

    if (false === (hashMap = YTILS.core.getHtmlTranslationTable('HTML_ENTITIES', quoteStyle)))
    {
      return false;
    }

    hashMap["'"] = ''';
    for (symbol in hashMap)
    {
      if (symbol && typeof symbol !== "undefined" && hashMap[symbol])
      {
        entity = hashMap[symbol];
        temp = temp.split(symbol).join(entity);
      }
    }

    return temp;
  },

  /**
   * Gets an array with this.length indexes with each one char.
   *
   * @param val
   * @return String
   */
  toArray: function(val)
  {
    var
    ret = [],
    length = val.length,
    i;

    for (i = 0; i < length; i++)
    {
      ret.push(val.charAt(i));
    }

    return ret;
  },

  /**
   * Extracts index pos from exploded val-string, that has been exploded by using delimitter.
   * This function throws an exception if parameters are not submitted correctly.
   *
   * @throws exception
   * @param val The string to extract one value from.
   * @param delimitter The delimitter for using val.split().
   * @param pos
   * @return string or null (if nothing can be returned.
   */
  extractFromSplit: function(val, delimitter, pos)
  {
    var
    splitted;

    if (typeof val === 'string' && typeof delimitter === 'string' && typeof pos === 'number')
    {
      pos = Math.floor(pos);
      splitted = val.split(delimitter);
      if (splitted.length > 1 && typeof splitted[pos] === 'string')
      {
        return splitted[pos];
      }
    }
    else
    {
      throw 'Invalid parameters submitted to YTILS.util.string.extractFromSplit().';
    }

    return null;
  }
};

}());