String Functions

• Below is a list of string-manipulation functions built into HFL.
• NOTE: These are normal functions, not object methods.
• Many of these functions have String object equivalents, described in the section titled "String Object" .
• substr(<string>, <offset>[, <length>[, <replacement>]])
  • Returns a sub-string of the string. This is a Perl-style substring function that works in one of three modes. It returns a string that is extracted from the original from a starting point for the length requested in the direction requested.
  • If the <offset> value is positive, the sub-string's starting point is that many characters from the start of the string, where the first character is offset 0. The direction of the sub-string will be toward the end of the string.
  • If the <offset> value is negative, the offset refers to the end of the string, and the starting point is that many characters from the end of the string, where the last character is offset -1. The direction of the sub-string will be toward the beginning of the string.
  • If the <length> value is omitted, the sub-string is all of the characters from the starting point for the rest of the string in the direction of the offset.
  • If the <length> value is specified, the sub-string is the number of characters of the length requested, from the starting point in the direction of the offset. If the value is negative, the end of the substring will be that many characters from the end of the string.
  • If the <replacement> value is not specified, returns the sub-string.
  • If the <replacement> value is specified, replaces the sub-string in the original string with the replacement characters, and returns the modified string.
• length(<string>)

  length(<array>)
  • Returns the number of characters in a string if passed a string.
  • Returns the number of elements in an array if passed an array.
• 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 = charAt($sz,1);                  // $ch is 'h'
      

• indexOf(<string>, <sub-string>[, <offset>])
  • Returns the index of the position of a sub-string within another string, or -1 if no match. The index value is 0-based.
  • If the offset value is specified, starts the search at that index position.
  • EXAMPLES:

    • var $sz = 'The quick brown fox', $sz2 = 'brown';
      var $i = indexOf($sz, $sz2);        // $i = 10
      var $j = indexOf($sz, 'jumped');    // $j = -1
      

• match(<expr>, <regex> [, 'as_array'])

   

  where:

  <expr>

  :=

  an expression that evaluates to a string

  <regex>

  :=

  a regular expression
  • Parses the <expr> string using the regular expression (or 'regex'), and returns the fields that matched, in one of two ways.
  • By default it sets global variables $1, $2, $3, and so on, up to $21 to hold the values of matched regex fields. These values can then be used as would any other variables in expressions and arguments to function calls.
  • If the 'as_array' option is is specified, the matched regex fields are also returned as an array, in the same way as the javascript 'match()' function.
  • EXAMPLES:

    • var $szLead = "  A.  MAIN TITLE";
      
      // Match pattern using an in-line regex string
      if (match($szLead, /^\s*([A-Z])\./)) {
        print("MATCHED OUTLINE LEVEL |$1| WITH MATCH FN USING INLINE REGEX");
        }
      
      // Match pattern using pre-defined regex string
      var $regex = /^\s*([A-Z])\./;
      if (match($szLead, $regex)) {
        print("MATCHED OUTLINE LEVEL |$1| WITH MATCH FN USING REGEX VARIABLE");
        }
      
      // Match pattern, and return results as an array
      if ($matches = match($szLead, /^\s*([A-Z])\./, 'as_array')) {
        printArray("MATCHED OUTLINE LEVEL |$1| WITH MATCH FN USING INLINE REGEX:",
                   $matches);
        }
      

• replace(<expr>, <regex>, <repl-str>)

  replace(<expr>, <sub-string>, <repl-str>)

   

  where:

  <expr>

  :=

  an expression that evaluates to a string

  <regex>

  :=

  a regular expression

  <sub-string>

  :=

  a string to match

  <repl-str>

  :=

  a string containing a replacement
  • Replaces a range of characters of the <expr> string that match the search pattern (<regex> or <sub-string>) with the characters of the <repl-str> string, and returns the modified string.
  • The function matches characters either using a regular expression (or 'regex'), or against a simple sub-string.
  • If a regex is used to match the characters, the replace() function also sets global variables $1, $2, $3, and so on, up to $21 to hold the values of matched regex fields. These values can then be used as would any other variables in expressions and arguments to function calls.
  • EXAMPLES:

    • var $sz, $szLead = "  A.  MAIN TITLE";
      
      // Replace the 'A.' with 'B.' using a regex, and also use the '$1' var
      if ($sz = replace($szLead, /^\s*([A-Z])\./, 'B.')) {
        print("REPLACED OUTLINE LEVEL |$1| WITH 'B.' USING INLINE REGEX\n"
              +"  sz = |$sz|");
        }
      
      // Replace the 'A.' with 'C.' using regex string variable
      var $regex = /^\s*([A-Z])\./;
      if (replace($szLead, $regex, 'C.')) {
        print("REPLACED OUTLINE LEVEL |A.| WITH 'C.' USING REGEX VARIABLE:\n"
              +"  sz = |$sz|");
        }
      
      // Replace the sub-string 'TITLE' with 'HEADING'
      if ($sz = replace($szLead, 'TITLE', 'HEADING')) {
        print("REPLACED 'TITLE' with 'HEADING':\n sz = |$sz|");
        }
      

• regex(<regex-patt>[, <regex-flags>])

   

  where:

  <regex-patt>

  :=

  regular-expression pattern characters

  <regex-flags>

  :=

  {<regex-flag> | <scope-re-flag>}+

  <regex-flag>

  :=

  s

  // Regex s: Treat match as a single line

  |

  m

  // Regex m: Match on multiple lines

  |

  i

  // Regex i: Match case-insensitive

  |

  g

  // Regex g: Match global: multiple matches

   

  <scope-re-flag> :=

  b

  // Scope ^: Match beginning of parent scope

  |

  e

  // Scope $: Match end of parent scope
  • Returns a regular expression <regex> object, which is the string portions of a 'RegExp' object, but without the object overhead.
  • This function allows a <regex> to be composed at run-time. The returned <regex> can be used in functions that take regex arguments, such as replace() and match() above, and for defining pattern-based scopes.
  • It also allows regular expressions to be composed that contain HTML tags, which overcomes a current limitation with the main parser. regex() allows the closing '>' character of the tag to be in a separate string.
  • Regex pattern matching in HFL follows the rules of regex patterns used in the Perl language. For more details about Perl's regex expression syntax and usage, consult the Perl documentation which can be found at http://perldoc.perl.org/perlre.html
  • The 'b' and 'e' flags modify the behavior of the '^' and '$' regex pattern characters in defscope scope declarations. They cause the characters to match the beginning and end characters of the parent scope, instead of the start and end of a string, respectively.
  • EXAMPLES:

    • // Define a scope that has an HTML within the pattern
      var $regex_fp_marker = regex('\n\<titled_topics_nlnl(.*?)\\'+'>\n');
      defscope first_page_marker(patt, $regex_fp_marker);
      
      // Match filenames with pattern that works for both Windows and Linux
      var $DSEP = ($system == 'WINDOWS' ? '\\' : '/');
      if (match($sz, regex('(([\w|\.]+)'+$DSEP+'([\w|\.]+))'))) {
        print("MATCHED FILENAME: |$1|");
        } 
      

• sprintf(<format-string>, <arg-list>)

  where:

  <arg-list>

  :=

  <arg> [, <arg>]*
  • Returns a string that is the result of expanding format fields within the <format-string>, applying the values in the argument list one at a time to each format field.
  • This is a Perl-style version of the 'sprintf()' function in the 'C' language. For more details, see the Perl documentation of 'sprintf' at http://perldoc.perl.org/functions/sprintf.html.
  • The following is an abbreviated list of the format field values which get replaced with an expansion of the <arg> values:
    • %%

      a percent sign (does not consume an <arg>)

      %c

      a character with the given number

      %s

      a string

      %d

      a signed integer, in decimal

      %u

      an unsigned integer, in decimal

      %o

      an unsigned integer, in octal

      %x

      an unsigned integer, in hexadecimal

      %e

      a floating-point number, in scientific notation

      %f

      a floating-point number, in fixed decimal notation

      %g

      a floating-point number, in %e or %f notation
• escapeHtml([<level>[, <starting-indent>]])

  where:

  <level>

  :=

  0

  or empty

  Escapes most common characters that cause conflicts

  1

  or 'all_punct'

  Escapes punctuation characters and whitespace

  2

  or 'all'

  Same as all_punct, plus adds <br > to each line

  3

  or 'full'

  Same as all, plus preserves indentation

  <starting-indent>

  :=

  Base indentation (default = that of 1st line)
  • Escapes HTML characters within the text values of a scope. This allows text to be displayed that will not be interpreted or adjusted by the browser, because they are now just characters.
  • If no level is specified, escapes punctuation characters such as '<' and '>', so they will not be treated as HTML tag delimiters by the browser.
  • If the 'all_punct' option is specified, escapes punctuation characters and whitespace (blanks and tabs).
  • If the 'all' option is specified, escapes punctuation characters and whitespace, and adds a
    tag to each line to preserve line breaks.
  • If the 'full' option is specified, escapes punctuation characters and whitespace, adds a
    tag to each line, and inserts leading non-breaking spaces to preserve indentation.
  • The optional <starting-indent> is the number of whitespace characters that will be ignored on each line of the range when using the 'full' option. By default, the starting indentation level is set to the number of whitespace characters in front of the first line in the range, so that all lines will display indentation relative to that line. This option would be used when the first line is not the left-most of the lines, or if you wish all lines to display with some leading whitespace. For example if the first line has 8 leading whitespace characters, but you wish to show three of them, then the <starting-indent> value would be set to 5.
• expandStr(<string-or-var>[, <vars-to-expand>])

  where

  <string-or-var>

  :=

  <string> | <var> | <pseudo-var>

  <vars-to-expand>

  :=

  'defined' | <var-list>

  <var-list>

  :=

  <var> [, <var>]*
  • Expands variable references within a quoted text string. The expansion can be all variable references or just specific ones.
  • If the 'defined' option is chosen, will only expand variables that have existing definitions, and will leave any other variable references alone. An example of a use would be to expand defined variables within the text of a cell. But leave alone anything that was not defined because it should just be treated as text.
  • If a list of variable names is provided, will only expand those references, and leave the other references alone. An example of a use would be to expand some variables within a file path, while leaving the others to be expanded later.
  • EXAMPLE

    • // Expand all variable references in cell's text
      $my_text = expandStr($text, 'defined');
      
      // Expand only the variable '$DL_DIR' but not '$file'
      $path = expandStr("$DL_DIR/$file.zip");
      

• split(<string>, <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 = split(str, ' ');       // s1 = ['the', 'quick', 'brown', 'fox']
      var s2 = split(str, ' ', 3);    // s2 = ['the', 'quick', 'brown']
      var s3 = split(str, /[io]/);    // s3 = ['the qu', 'ck br', 'wn f', 'x']
      var s4 = split(str, '', 5);     // s4 = ['t', 'h', 'e', ' ', 'q']
      var s5 = split(str);            // s5 = ['the quick brown fox']
      

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

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

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

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

• countLeadWS(<string>[, <num-chars-per-tab>])
  • Counts the number of leading whitespace characters (tabs, blanks and newlines) in the string, and returns a number that represents the effective number of spaces.
  • Tabs will be treated as indexing to the next tab-stop, spaced at <num-chars-per-tab> spaces. If <num-chars-per-tab> is omitted, a tab-stop of 8 is the default.
• trimStr(<string>)
  • 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 = trimStr(x);                         // y is 'Now is the time'
    

• trimLeftStr(<string>)
  • 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 = trimLeftStr(x);                     // y is 'Now is the time  '
    

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

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

• cmp(<value1>' , <value2>)'
  • Compares two values as strings, and returns a number indicating their relative string collating order.
  • Returns -1 if <value1> is less than (sorts before) <value2>
  • Returns 1 if <value1> is greater than (sorts after) <value2>
  • Returns 0 if they are equal
  • This routine can be used by custom comparision functions used by sort().
  • NOTE: If the values being passed are integers, the sorting order will be by their collating order, not their numeric value. Thus for example, 12 would sort before 2.
  • EXAMPLE:

  • var pet_names = [['dog', 'fido'], ['cat', 'fluffy'], ['parrot', 'sam'],
                          ['fish', 'goldie']];
    
    function mysortrev($a, $b) {return cmp($b[0], $a[0]);}
    
    var pet_names_reversed = sort(pet_names, mysortrev);
    

• isWS(<string>)

  isBlank(<string>)
  • Returns true if the string contains only whitespace characters (tabs, blanks and newlines)
• concatStr(<string>, <string>[, <string>]*)
  • Concatenates strings into a single larger string. This function would be used instead of the '+' operator when neither of the two strings are enclosed in quotes.
  • This function is necessary because unlike javascript, HFL only overloads the '+' operator when one or both operands are quoted.
  • EXAMPLE

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

String functions associated with cells

• The following functions access and modify text cells, and access and modify string fields within cells.
• insert_text(<expr>)
  • Inserts a new text cell into the page. The <expr> argument can be any valid expression that can be converted to a string.
  • If used in an 'inline' format cell (i.e. the code block containing the HFL instructions is embedded in text), it will insert the text cell just after the format cell.
  • Returns the cell number of the inserted cell containing the new text.
  • EXAMPLES:

    • <p>'Frank' begins with an '<\ insert_text(substr('Frank', 0, 1));\>'</p>
      <p>The sum of 4 and 3 is <\ insert_text(4 + 3);\></p>
      

  • would output:

    • <p>'Frank' begins with an 'F'</p>
      <p>THE SUM OF 4 AND 3 IS 7</p>
      

• getLeadWS()
  • Returns the whitespace characters (tabs, blanks and newlines) that occur at the start of the text of the scope, including in inner descendent cells. Stops searching when a cell has a tag whose scope level (SL) is higher than that of <span>.
• expandText([<options>])

   

  where

  <options>

  :=

  ['all',] [<vars-to-expand>]

  <vars-to-expand>

  :=

  'defined' | <var-list>

  <var-list>

  :=

  <var> [, <var>]*
  • Similar to expandStr() above , except that it expands variable references within the text fields of all cells of the current scope, and if 'all' is specified, to their descendents.
  • See expandStr() above for details on the options.
  • If the 'all' option is chosen, it is syntactic sugar for:

    • scope (cell:..all) {
          if ($text) {
              text = expandStr($text, [<options>]);
              }
          }
      

  • EXAMPLE

  • // Expand all defined variables of all of the cells in scope 'p:2'
    p:2{ expandText('all', 'defined'); }
    

• getFilename()
  • Returns the filename of the current file assigned to the page
• setFilename(<filename>)
  • Assigns the specfied filename to the current page