String Object

NOTE: All of the String object methods below have non-object function equivalents, described in the section titled "HFL String Functions" .

Creating String objects

  • 'String' objects can be created using the 'new' operator:
  • new String( <data> )
    • Creates a new String object after converting the <data> value to a literal string.
  • A 'String' object can also be created by coercing a string literal to a string object by adding a property to it:
    • EXAMPLE:

      • // Define a simple string
        var $street1 = "1st Avenue";

        // Prints "typeof(street1) = string"
        print("typeof(street1) = ".+typeof($street1));

        // Add an object property to the string, converting it to an object
        $street1.cross_street = "Main Street";

        // Prints "typeof(street1) = object"
        print("typeof(street1) = ".+typeof($street1));

Using string primitives as String objects

  • Any string primitive may be used in place of a String object to call String methods or access String object properties. HFL will promote the string primitive to a String object, before calling the method or accessing the object property.
  • If an object property is assigned to a string primitive, the assignment will be ignored unless the string primitive was specified from a storage location such as a local or global variable, in which case it replaces the stored primitive string with the promoted String object.
    • EXAMPLE:

      • var $sz = 'The quick fox jumped over the lazy dog';

        // Prints "|The quick fox jumped over the lazy dog|"
        print("sz = |$sz|");

        // Promotes the string to a String object then prints "Length is 28"
        print("Length is ".+$sz.length);

        // Setting an object property promotes the string primitive to an object
        $sz.color = "brown";

        // Prints "typeof(sz) = object"
        print("typeof(sz) = ".+typeof($sz));

        // Still prints "|The quick fox jumped over the lazy dog|"
        print("sz = |$sz|");

String Properties

  • <str>.length
    • Returns the length in characters of the string.
    • EXAMPLE:

      • var sz = 'Now is the time for all';
        print("Length is ".+sz.length);          // Prints "Length is 23"

String Methods

  • <str>.charAt(<string>, <index>)
    • Returns the character within the string at the index, where the first character has an index 0;
    • EXAMPLE:

      • var $sz = 'The quick brown fox jumped over the lazy dog.';
        var $ch = $sz.charAt(1);                  // $ch is 'h'

  • <str>.indexOf(<search-string> [, <from-index>])
    • Returns the index of the <search-string> within the string, starting at the character at index <from-index> if specified or at index 0 if not.
    • EXAMPLE:

      • var sz = 'Now is the time for all';
        var i = sz.indexOf('i', 6);               // i is 12

  • <str>.valueOf()
    • Returns the string value of a string object.
    • EXAMPLE:

      • var sz = new String(Math.PI);
        print("sz = |".+sz.valueOf().+"|");     // Prints "sz = |3.14159265358979|"

  • <str>.substr(<start-index> [, <length>])
    • Returns a substring of the string starting at the <start-index> index, for the length given by <length> if specified, or the remainder of the string if not.
    • If <offset> is negative, substring will start that many characters from the end.
    • If <length> is negative, the end of the substring will be that many characters from the end of the string.
    • EXAMPLES:

      • var sz = new String(Math.PI);
        print("sz = |".+sz.substr(0, 4).+"|");    // Prints "sz = |3.14|"
        print("sz = |".+sz.substr(0, -9).+"|");   // Prints "sz = |3.14159|"
        print("sz = |".+sz.substr(-5).+"|");      // Prints "sz = |58979|"
        print("sz = |".+sz.substr(-5, 2).+"|");   // Prints "sz = |58|"

  • <str>.substring(<start-index> [, <end-index>])
    • Returns a substring of the string starting at the character position at the <start-index> index, and ending at the character position at the <end-index> index if specified, or the remainder of the string if not.
    • If <start-index> equals <end-index> returns an empty string.
    • If <end-index> is not specified it will be treated as if it were the length of the string.
    • If either <start-index> or <end-index> are negative or undefined it will be treated as a zero.
    • If either <start-index> or <end-index> is greater than the length of the string it will be treated as if it were the length of the string.
    • EXAMPLES:

      • var sz = "3.14159"
        print("sz = |".+sz.substring(0, 4).+"|");    // Prints "sz = |3.14|"
        print("sz = |".+sz.substring(2).+"|");       // Prints "sz = |14159|"
        print("sz = |".+sz.substring(-5, 5).+"|");   // Prints "sz = |3.1415|"
        print("sz = |".+sz.substring(3, 3).+"|");    // Prints "sz = ||"

  • <str>.match(<regex>)
     
    where:
    <regex>
    :=
    a regular expression
    • Parses the <expr> string using the regular expression (or 'regex'), and returns the fields that matched as an array.
    • EXAMPLES:

      • var $szLead = "  A.  MAIN TITLE";

        // Match pattern using an in-line regex string
        if ($matches = $szLead.match(/^\s*([A-Z])\./)) {
          printArray("MATCHED OUTLINE LEVEL |A| WITH MATCH FN USING INLINE REGEX:",
                     $matches);
          }

        // Match pattern using pre-defined regex string
        var $regex = /^\s*([A-Z])\./;
        if ($matches = $szLead.match($regex)) {
          printArray("MATCHED OUTLINE LEVEL |A| WITH MATCH FN USING REGEX VAR:",
                     $matches);
          }

  • <str>.replace(<regex>, <repl-str>)
    <str>.replace(<sub-string>, <repl-str>)
     
    where:
    <regex>
    :=
    a regular expression
    <sub-string>
    :=
    a string to match
    <repl-str>
    :=
    a string containing a replacement
    • Replaces a range of characters of the string that match the search pattern (<regex> or <sub-string>) with the characters of the <repl-str> string, and returns the modified string.
    • It matches characters either using a regular expression (or 'regex'), or against a simple sub-string.
    • DIFFERENCES FROM JAVASCRIPT
      • The callback-function option is not supported at this time.
    • EXAMPLES:

      • var $sz, $szLead = "  A.  MAIN TITLE";

        // Replace the 'A.' with 'B.' using an in-line regex
        if ($sz = szLead.replace(/^\s*([A-Z])\./, 'B.')) {
          print("REPLACED OUTLINE LEVEL |A| WITH 'B.' USING INLINE REGEX\n"
                .+"  sz = |$sz|");
          }

        // Replace the 'A.' with 'C.' using regex string variable
        var $regex = /^\s*([A-Z])\./;
        if ($sz = $szLead.replace($regex, 'C.')) {
          print("REPLACED OUTLINE LEVEL |A.| WITH 'C.' USING REGEX VARIABLE:\n"
                .+"  sz = |$sz|");
          }

        // Replace the sub-string 'TITLE' with 'HEADING'
        if ($sz = $szLead.replace('TITLE', 'HEADING')) {
          print("REPLACED 'TITLE' with 'HEADING':\n sz = |$sz|");
          }

  • <str>.split(<separator> [,<limit>])
     
    where:
    <separator>
    :=
    <sub-string> | <regex-patt>
    <regex-patt>
    :=
    regular-expression pattern characters
    <limit>
    :=
    an integer specifying max number of splits
    • Splits the string into an array of substrings, that are separated by the <separator> argument, which can be either a simple string or a regular expression (regex).
    • If the <separator> argument is an empty string, the returned array will have one element for each character in the original string.
    • If the <separator> argument is missing or undefined, the returned array will contain just one element, the original string.
    • If the <limit> argument is specified, it limits the number of entries in the generated array to the first <limit> elements, and discards the rest.
    • EXAMPLES:

      • var str = 'the quick brown fox';
        var s1 = str.split(' ');        // s1 = ['the', 'quick', 'brown', 'fox']
        var s2 = str.split(' ', 3);     // s2 = ['the', 'quick', 'brown']
        var s3 = str.split(/[io]/);     // s3 = ['the qu', 'ck br', 'wn f', 'x']
        var s4 = str.split('', 5);      // s4 = ['t', 'h', 'e', ' ', 'q']
        var s5 = str.split();           // s5 = ['the quick brown fox']

  • <str>.toLowerCase()
    • Converts the characters of the string to lowercase, and returns the result.
    • EXAMPLE

      • var str = 'The Quick Brown Fox';
        var str2 = str.toLowerCase(str);        // str2 is 'the quick brown fox'

  • <str>.toUpperCase()
    • Converts the characters of the string to uppercase, and returns the result.
    • EXAMPLE

      • var str = 'The Quick Brown Fox';
        var str2 = str.toUpperCase();           // str2 is 'THE QUICK BROWN FOX'

  • <str>.trim()
    • Strips off whitespace characters (tabs, blanks and newlines) from the front and end of the text string.
    • EXAMPLE

    • var x = '  Now is the time  ';
      var y = x.trim();                           // y is 'Now is the time'

  • <str>.trimLeft()
    • Strips off whitespace characters (tabs, blanks and newlines) from the front end of the text string.
    • EXAMPLE

    • var x = '  Now is the time  ';
      var y = x.trimLeft();                       // y is 'Now is the time  '

  • <str>.trimRight()
    • Strips off whitespace characters (tabs, blanks and newlines) from the end of the text string.
    • EXAMPLE

    • var x = '  Now is the time  ';
      var y = x.trimRight();                      // y is '  Now is the time'

  • <str>.concat(<string> [, <string>]*)
    • Concatenates strings into a single larger string. This function has similar functionality to the '+' operator, but can take any number of string arguments.
    • EXAMPLE

    • var x = 'Now is';
      var y = ' the time';
      var z = ' for all';
      var s = x.concat(y, z);                     // s is 'Now is the time for all'