String Manipulation Utilities

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

  /**
   * Truncate string to specified length and add ellipsis
   *
   * @param {string} str - String to truncate
   * @param {number} maxLength - Maximum length
   * @param {string} suffix - Suffix to add (default: '...')
   * @returns {string} Truncated string
   */
  truncate: function(str, maxLength, suffix) {
    if (!str || str.length <= maxLength) {
      return str;
    }

    suffix = suffix || '...';
    var trimmedLength = maxLength - suffix.length;

    return str.substring(0, trimmedLength) + suffix;
  },

  /**
   * Convert string to title case (capitalize first letter of each word)
   *
   * @param {string} str - String to convert
   * @returns {string} Title cased string
   */
  toTitleCase: function(str) {
    if (!str) {
      return '';
    }

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

  /**
   * Convert string to camelCase
   *
   * @param {string} str - String to convert
   * @returns {string} camelCase string
   */
  toCamelCase: function(str) {
    if (!str) {
      return '';
    }

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

  /**
   * Convert string to snake_case
   *
   * @param {string} str - String to convert
   * @returns {string} snake_case string
   */
  toSnakeCase: function(str) {
    if (!str) {
      return '';
    }

    return str
      .replace(/\W+/g, ' ')
      .split(/ |\B(?=[A-Z])/)
      .map(function(word) { return word.toLowerCase(); })
      .join('_');
  },

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

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

  /**
   * Extract email addresses from text
   *
   * @param {string} text - Text containing email addresses
   * @returns {Array} Array of email addresses found
   */
  extractEmails: function(text) {
    if (!text) {
      return [];
    }

    var emailRegex = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
    var matches = text.match(emailRegex);

    return matches || [];
  },

  /**
   * Mask sensitive data (e.g., SSN, credit card)
   *
   * @param {string} str - String to mask
   * @param {number} visibleChars - Number of characters to leave visible at end
   * @param {string} maskChar - Character to use for masking (default: '*')
   * @returns {string} Masked string
   */
  maskString: 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);
  },

  /**
   * Generate a slug from text (URL-friendly string)
   *
   * @param {string} text - Text to convert
   * @returns {string} URL-friendly slug
   */
  slugify: function(text) {
    if (!text) {
      return '';
    }

    return text
      .toLowerCase()
      .trim()
      .replace(/[^\w\s-]/g, '')  // Remove special chars
      .replace(/[\s_-]+/g, '-')  // Replace spaces with -
      .replace(/^-+|-+$/g, '');  // Trim - from ends
  },

  /**
   * Count words in text
   *
   * @param {string} text - Text to count
   * @returns {number} Word count
   */
  wordCount: function(text) {
    if (!text) {
      return 0;
    }

    return text.trim().split(/\s+/).length;
  },

  /**
   * Check if string is valid email
   *
   * @param {string} email - Email to validate
   * @returns {boolean} True if valid email format
   */
  isValidEmail: function(email) {
    if (!email) {
      return false;
    }

    var emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
    return emailRegex.test(email);
  },

  /**
   * Check if string is valid phone number (US format)
   *
   * @param {string} phone - Phone number to validate
   * @returns {boolean} True if valid phone format
   */
  isValidPhone: function(phone) {
    if (!phone) {
      return false;
    }

    // Remove all non-digits
    var digits = phone.replace(/\D/g, '');

    // Check for valid length (10 or 11 digits with country code)
    return digits.length === 10 || digits.length === 11;
  },

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

    format = format || 'us';
    var digits = phone.replace(/\D/g, '');

    if (format === 'us' && digits.length === 10) {
      return '(' + digits.substring(0, 3) + ') ' +
             digits.substring(3, 6) + '-' +
             digits.substring(6);
    } else 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
  },

  /**
   * Generate random string
   *
   * @param {number} length - Length of string to generate
   * @param {string} charset - Character set: 'alphanumeric' (default), 'alpha', 'numeric'
   * @returns {string} Random string
   */
  generateRandom: function(length, charset) {
    length = length || 10;
    charset = charset || 'alphanumeric';

    var chars = '';
    if (charset === 'alpha') {
      chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
    } else if (charset === 'numeric') {
      chars = '0123456789';
    } else {
      chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
    }

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

    return result;
  },

  type: 'StringUtils'
};