## page was renamed from DevCenter/Documentation/ExtensionObjects/StringUtilities
= StringUtilities =

{{{#!rst
Purpose:
  Extend the available string processing methods to XSL to include message formatting, specialized text escaping, regular expression operations, etc.

Namespace:
  urn:WebWorks-XSLT-Extension-StringUtilities

Prefix:
  wwstring

Methods:
  ToLower(string  value):
    Convert the given string to lowercase.

    Returns:
      String.

    Example:
      Convert ``UppERcAse`` to lowercase.

      ::
      
        <xsl:value-of select="wwstring:ToLower('UppERcAse')" />


  ToUpper(string  value):
    Convert the given string to uppercase.

    Returns:
      String.

    Example:
      Convert ``lOwErcAsE`` to uppercase.

      ::
      
        <xsl:value-of select="wwstring:ToUpper('lOwErcAsE')" />



  Replace(string  input, string  search, string  replacement):
    Replace all occurances of ``search`` in ``input`` with ``replacement``.

    Returns:
      String.

    Example:
      Replace all instances of ``<letter>`` with ``O``.

      ::
      
        <xsl:value-of select="wwstring:Replace('<letter>scar's <letter>nly <letter>strich <letter>iled an <letter>range <letter>wl t<letter>day.', '<letter>', 'o')" />


  MatchExpression(string  input, string  searchExpressionAsString, string  replacement):
    Return success of match for ``matchExpressionAsString`` in ``input``.
    
    .. note::
      `Expresso Regular Expression Tool`_

.. _Expresso Regular Expression Tool:
  http://www.codeproject.com/dotnet/RegexTutorial.asp

    Returns:
      Boolean.

    Example:
      Contains 3-4 "a"s?

      ::
      
        <xsl:value-of select="wwstring:MatchExpression('The end of aa sentenceaaaaalways leaves me sad.', 'a{3-4}')" />


  MatchExpressionValue(string  input, string  matchExpressionAsString):
    Return value of match for ``matchExpressionAsString`` in ``input``.
    
    .. note::
      `Expresso Regular Expression Tool`_

.. _Expresso Regular Expression Tool:
  http://www.codeproject.com/dotnet/RegexTutorial.asp

    Returns:
      String.

    Example:
      Value of 3-4 "a"s.

      ::
      
        <xsl:value-of select="wwstring:MatchExpressionValue('The end of aa sentenceaaaaalways leaves me sad.', 'a{3-4}')" />


  ReplaceWithExpression(string  input, string  searchExpressionAsString, string  replacement):
    Replace all occurances of ``searchExpressionAsString`` in ``input`` with ``replacement``.
    
    .. note::
      `Expresso Regular Expression Tool`_

.. _Expresso Regular Expression Tool:
  http://www.codeproject.com/dotnet/RegexTutorial.asp

    Returns:
      String.

    Example:
      Replace runs of 3-4 "a"s with "\. ".

      ::
      
        <xsl:value-of select="wwstring:ReplaceWithExpression('The end of aa sentenceaaaaalways leaves me sad.', 'a{3-4}', '. ')" />


  CSSClassName(string  styleName):
    Convert the given string into a valid CSS class name.

    Returns:
      String.

    Example:
      Convert ``Blue_Moon.Detective;Agency`` into a valid CSS style name.

      ::
      
        <xsl:value-of select="wwstring:CSSClassName('Blue_Moon.Detective;Agency')" />


  WebWorksHelpContextOrTopic(string  value):
    Converts the given string intto a valid WebWorks Help context or topic string.

    .. note::
      WebWorks Help context and topic strings may only contain the characters A-Z, a-z, 0-9, and ``_``.

    Returns:
      String.

    Example:
      Convert ``A long time...`` into a valid WebWorks Help context or topic name.
      
      ::
      
        <xsl:value-of select="wwstring:WebWorksHelpContextOrTopic('A long time...')" />


  MD5Checksum(string  value):
    Compute the MD5 checksum on the given string.

    Returns:
      MD5 checksum as string.

    Example:
      Determine the MD5 signature for ``A long time ago, way back in history, when all there was to drink, was nothing but cups 'o tea.``.

      ::
      
        <xsl:value-of select="wwstring:MD5Checksum('A long time ago, way back in history, when all there was to drink, was nothing but cups \'o tea.')" />


  EscapeForXMLAttribute(string  value):
    Escape string assume it will be written as the value of an XML attribute.

    Returns:
      String.

    Example:
      Write ``onClick`` handler for ``<div>`` tag.
      
      ::
      
        <html:div onClick="{wwstring:EscapeForXMLAttribute('alert(\'Boo!\');')}">
         Click me!
        </html:div>


  JavaScriptEncoding(string  value):
    Convert all non-ASCII characters to Unicode escape sequences.  Also convert all ASCII characters less than 32 along with problematic escape characters, i.e. ``\``, to Unicode escape sequences.

    Returns:
      String.

    Example:
      Convert ``Hello\nworld!\n`` to JavaScript encoded text.

      ::
      
        <xsl:value-of select="wwstring:JavaScriptEncoding('Hello\nworld!\n')" />


  PalmReaderEncoding(string  encodingName, string  value):
    Encode string as required by Palm Reader.

    Returns:
      String.

    Example:
      Encode ``Black moon rising\nwas entertaining.`` for Palm Reader.

      ::
      
        <xsl:value-of select="wwstring:PalmReaderEncoding('Black moon rising\nwas entertaining.')" />


  Format(string  format, string  argument1, *string  argument2*, *string  argument3*, *string  argument4*, *string  argument5*, *string  argument6*, *string  argument7*, *string  argument8*, *string  argument9*, string  argument10*):
    Format a message using the C# string formatter.

    See also `C# String Formatting Information`_.

.. _C# String Formatting Information:
  http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemstringclassformattopic3.asp

    Returns:
      String.

    Example:
      Format message ``17 total, 15 of 17.``.

      ::
      
        <xsl:value-of select="wwstring:Format('{0} total, {1} of {0}.', 17, 15)" />
}}}