String Manipulation Utility

var StringUtils = Class.create();
StringUtils.prototype = {

  /**
   * Convert string to title case
   * @param {string} str
   * @returns {string}
   */
  toTitleCase: function(str) {
    if (!str) return '';

    return str.toLowerCase().replace(/\b\w/g, function(char) {
      return char.toUpperCase();
    });
  },

  /**
   * Convert string to camel case
   * @param {string} str
   * @returns {string}
   */
  toCamelCase: function(str) {
    if (!str) return '';

    return str.toLowerCase()
      .replace(/[^a-zA-Z0-9]+(.)/g, function(match, char) {
        return char.toUpperCase();
      });
  },

  /**
   * Convert string to snake case
   * @param {string} str
   * @returns {string}
   */
  toSnakeCase: function(str) {
    if (!str) return '';

    return str
      .replace(/([A-Z])/g, '_$1')
      .replace(/[^a-zA-Z0-9]+/g, '_')
      .toLowerCase()
      .replace(/^_+|_+$/g, '');
  },

  /**
   * Truncate string to specified length with ellipsis
   * @param {string} str
   * @param {number} maxLength
   * @param {string} suffix - Default: '...'
   * @returns {string}
   */
  truncate: function(str, maxLength, suffix) {
    if (!str) return '';
    suffix = suffix || '...';

    if (str.length <= maxLength) {
      return str;
    }

    return str.substring(0, maxLength - suffix.length) + suffix;
  },

  /**
   * Remove HTML tags from string
   * @param {string} str
   * @returns {string}
   */
  stripHtml: function(str) {
    if (!str) return '';

    return str.replace(/<[^>]*>/g, '');
  },

  /**
   * Escape HTML special characters
   * @param {string} str
   * @returns {string}
   */
  escapeHtml: function(str) {
    if (!str) return '';

    var map = {
      '&': '&amp;',
      '<': '&lt;',
      '>': '&gt;',
      '"': '&quot;',
      "'": '&#039;'
    };

    return str.replace(/[&<>"']/g, function(char) {
      return map[char];
    });
  },

  /**
   * Mask sensitive information (e.g., credit card, SSN)
   * @param {string} str
   * @param {number} visibleChars - Number of chars to show at end
   * @param {string} maskChar - Character to use for masking
   * @returns {string}
   */
  mask: function(str, visibleChars, maskChar) {
    if (!str) return '';

    visibleChars = visibleChars || 4;
    maskChar = maskChar || '*';

    if (str.length <= visibleChars) {
      return str;
    }

    var masked = '';
    for (var i = 0; i < str.length - visibleChars; i++) {
      masked += maskChar;
    }

    return masked + str.substring(str.length - visibleChars);
  },

  /**
   * Extract numbers from string
   * @param {string} str
   * @returns {string} Numbers only
   */
  extractNumbers: function(str) {
    if (!str) return '';

    return str.replace(/\D/g, '');
  },

  /**
   * Format phone number
   * @param {string} phone
   * @param {string} format - 'us', 'international'
   * @returns {string}
   */
  formatPhone: function(phone, format) {
    if (!phone) return '';

    var digits = this.extractNumbers(phone);
    format = format || 'us';

    if (format === 'us' && digits.length === 10) {
      return '(' + digits.substring(0, 3) + ') ' +
             digits.substring(3, 6) + '-' +
             digits.substring(6);
    }

    if (format === 'international' && digits.length === 11) {
      return '+' + digits.substring(0, 1) + ' (' +
             digits.substring(1, 4) + ') ' +
             digits.substring(4, 7) + '-' +
             digits.substring(7);
    }

    return phone;  // Return original if can't format
  },

  /**
   * Slugify string (URL-friendly)
   * @param {string} str
   * @returns {string}
   */
  slugify: function(str) {
    if (!str) return '';

    return str
      .toLowerCase()
      .replace(/[^\w\s-]/g, '')  // Remove special chars
      .replace(/[\s_]+/g, '-')    // Replace spaces/underscores with hyphens
      .replace(/^-+|-+$/g, '');   // Remove leading/trailing hyphens
  },

  /**
   * Generate random string
   * @param {number} length
   * @param {string} charset - 'alphanumeric', 'alpha', 'numeric', 'hex'
   * @returns {string}
   */
  random: function(length, charset) {
    length = length || 10;
    charset = charset || 'alphanumeric';

    var chars = {
      alphanumeric: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789',
      alpha: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
      numeric: '0123456789',
      hex: '0123456789abcdef'
    };

    var charSet = chars[charset] || chars.alphanumeric;
    var result = '';

    for (var i = 0; i < length; i++) {
      var randomIndex = Math.floor(Math.random() * charSet.length);
      result += charSet.charAt(randomIndex);
    }

    return result;
  },

  /**
   * Check if string is valid email
   * @param {string} email
   * @returns {boolean}
   */
  isValidEmail: function(email) {
    if (!email) return false;

    var emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    return emailRegex.test(email);
  },

  /**
   * Pluralize word based on count
   * @param {number} count
   * @param {string} singular
   * @param {string} plural - Optional, defaults to singular + 's'
   * @returns {string}
   */
  pluralize: function(count, singular, plural) {
    plural = plural || singular + 's';
    return count === 1 ? singular : plural;
  },

  /**
   * Calculate string similarity (Levenshtein distance)
   * @param {string} str1
   * @param {string} str2
   * @returns {number} Similarity percentage (0-100)
   */
  similarity: function(str1, str2) {
    if (!str1 || !str2) return 0;
    if (str1 === str2) return 100;

    var longer = str1.length > str2.length ? str1 : str2;
    var shorter = str1.length > str2.length ? str2 : str1;

    if (longer.length === 0) return 100;

    var distance = this._levenshteinDistance(longer, shorter);
    return ((longer.length - distance) / longer.length) * 100;
  },

  /**
   * Calculate Levenshtein distance between two strings
   * @private
   */
  _levenshteinDistance: function(str1, str2) {
    var matrix = [];

    for (var i = 0; i <= str2.length; i++) {
      matrix[i] = [i];
    }

    for (var j = 0; j <= str1.length; j++) {
      matrix[0][j] = j;
    }

    for (var i = 1; i <= str2.length; i++) {
      for (var j = 1; j <= str1.length; j++) {
        if (str2.charAt(i - 1) === str1.charAt(j - 1)) {
          matrix[i][j] = matrix[i - 1][j - 1];
        } else {
          matrix[i][j] = Math.min(
            matrix[i - 1][j - 1] + 1,  // substitution
            matrix[i][j - 1] + 1,      // insertion
            matrix[i - 1][j] + 1       // deletion
          );
        }
      }
    }

    return matrix[str2.length][str1.length];
  },

  type: 'StringUtils'
};