xHarbour Reference Documentation > Function Reference

HB_RegExAll()

Parses a string and fills an array with parsing information.

Syntax

HB_RegExAll( <cRegEx>         , ;
             <cString>        , ;
            [<lCaseSensitive>], ;
            [<lNewLine>]      , ;
            [<nMaxMatches>]   , ;
            [<nWichMatch>]    , ;
            [<lMatchOnly>]      ) --> aAllRegexMatches

Arguments

<cRegEx>

This is a character string holding the search pattern as a literal regular expression. Alternatively, the return value of HB_RegExComp() can be used.

<cString>

This is the character string being searched for a match.

<lCaseSensitive>

This parameter defaults to .T. (true) so that the resulting compiled regular expression performs a case sensitive search. Passing .F. (false) results in a case insensitive search.

<lNewLine>

This parameter defaults to .F. (false).

<nMaxMatches>

This is a numeric value indicating the maximum number of matches to return. The default value is zero which returns all matches.

<nWichMatch>

This parameter is numeric and specifies the type of match to return. It defaults to zero which means that the function returns the whole match and sub-matches, if any. The value 1 instructs the function to return only whole matches, 2 means the first sub-match in the whole match, 3 is the second sub-match in the whole match, and so forth.

<lMatchOnly>

This parameter defaults to .T. (true) so that only matched substrings are included in the returned array. When passing .F. (false) the array includes the numeric start and end positions of the substrings found in <cString>.

Return

The function returns an array filled with the found substrings matching the regular expression. If no match is found, the return value is NIL. The array is two dimensional when <lMatchOnly> is .T. (default), and three dimensional when <lMatchOnly> is set to .F. (false).

Description

Function HB_RegExAll() searches a character string using a regular expression and collects matching substrings in an array, which is returned. The array is two dimensional when <lMatchOnly> is .T. (true), which is the default. The first column of the array contains whole matches, while subsequent columns contain sub-matches found in the whole match.

When <lMatchOnly> is .F. (false), the numeric start and end positions of the matched substrings are determined in addition and the result is a three dimensional array of the following structure:

  aMatch := ;
  { ;
    { ;
      { <cWholeMatch1>, <nStart>, <nEnd> }, ;
      { <cSubMatch11> , <nStart>, <nEnd> }, ;
      { <cSubMatch1N> , <nStart>, <nEnd> }, ;
    } , ;
    { ;
      { <cWholeMatchN>, <nStart>, <nEnd> }, ;
      { <cSubMatchN1> , <nStart>, <nEnd> }, ;
      { <cSubMatchNN> , <nStart>, <nEnd> }, ;
    } ;
  }

The example program outlines the possible return values of HB_RegExAll() in detail.

Info

See also:	HAS, HB_AtX(), HB_RegEx(), HB_RegExComp(), HB_RegExReplace(), HB_RegExSplit(), LIKE
Category:	Character functions , Regular expressions , xHarbour extensions
Source:	rtl\regex.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Examples

// The example demonstrates the return values of HB_RegExAll() by
// matching a text that contains 4 ISO formatted dates.

   PROCEDURE Main
      LOCAL cRegEx := "([0-9]{4})[-/]([0-9]{1,2})[-/]([0-9]{1,2})"
      LOCAL cText  := "Our shop is closed from 2006/10/25 to 2006/11/1 " + ;
                      "and 2006/12/24 to 2007/1/3"
      LOCAL aMatch, i, j

      CLS
      ? "Text to match:"
      ? cText
      ?
      ? "Matching without positions"
      ?
      ? "All matches and sub-matches"
      aMatch := HB_RegExAll( cRegEx, cText )
      AEval( aMatch, {|a| QOut(ValToPrg(a)) } )
      WAIT
      CLS

      ? "Text to match:"
      ? cText
      ?
      ? "Matching with positions"
      ?
      ? "One whole match"
      aMatch := HB_RegExAll( cRegEx, cText, .T., .T., 1, 1, .F. )
      AEval( aMatch, {|a| QOut(ValToPrg(a)) } )
      ?
      ? "First sub-match of one whole match"
      aMatch := HB_RegExAll( cRegEx, cText, .T., .T., 1, 2, .F. )
      AEval( aMatch, {|a| QOut(ValToPrg(a)) } )
      ?
      ? "Second sub-match of one whole match"
      aMatch := HB_RegExAll( cRegEx, cText, .T., .T., 1, 3, .F. )
      AEval( aMatch, {|a| QOut(ValToPrg(a)) } )
      ?
      ? "Third sub-match of one whole match"
      aMatch := HB_RegExAll( cRegEx, cText, .T., .T., 1, 4, .F. )
      AEval( aMatch, {|a| QOut(ValToPrg(a)) } )
      ?
      ? "Two whole matches"
      aMatch := HB_RegExAll( cRegEx, cText, .T., .T., 2, 1, .F. )
      AEval( aMatch, {|a| QOut(ValToPrg(a)) } )
      ?
      ? "First sub-match of two whole matches"
      aMatch := HB_RegExAll( cRegEx, cText, .T., .T., 2, 2, .F. )
      AEval( aMatch, {|a| QOut(ValToPrg(a)) } )
      ?
      ? "Second sub-match of two whole matches"
      aMatch := HB_RegExAll( cRegEx, cText, .T., .T., 2, 3, .F. )
      AEval( aMatch, {|a| QOut(ValToPrg(a)) } )
      ?
      ? "Third sub-match of two whole matches"
      aMatch := HB_RegExAll( cRegEx, cText, .T., .T., 2, 4, .F. )
      AEval( aMatch, {|a| QOut(ValToPrg(a)) } )
      ?
      ? "All whole matches"
      aMatch := HB_RegExAll( cRegEx, cText, .T., .T., 0, 1, .F. )
      AEval( aMatch, {|a| QOut(ValToPrg(a)) } )
      ?
      ? "All first sub-matches"
      aMatch := HB_RegExAll( cRegEx, cText, .T., .T., 0, 2, .F. )
      AEval( aMatch, {|a| QOut(ValToPrg(a)) } )

      WAIT
      CLS
      ? "Text to match:"
      ? cText
      ?
      ? "All whole matches including sub-matches"
      aMatch := HB_RegExAll( cRegEx, cText,,,,, .F. )

      FOR i:=1 TO Len( aMatch )
          ?
          FOR j:=1 TO Len( aMatch[i] )
              IF j == 1
                 ? "Whole match"
              ELSE
                 ? "- sub-match"
              ENDIF
              ?? " found:", aMatch[i,j,1]
              ?? " Start:", aMatch[i,j,2]
              ?? " End:"  , aMatch[i,j,3]
          NEXT
      NEXT
   RETURN

// The example locates the opening and closing tags in an HTML or XML
// file and displays them along with their positions. Note that the
// end position of opening tags is found with the At() function since
// opening HTML and XML tags may include attributes.

   PROCEDURE Main
      LOCAL cText := Memoread( "Test.htm" )
      LOCAL cRegEx := "<[A-Z][A-Z0-9]*|</[A-Z][A-Z0-9]*>"
      LOCAL aMatch, i, nStart, nEnd

      aMatch := HB_RegExAll( cRegEx, cText, .F., .T., 0, 0, .F. )

      FOR i:=1 TO Len( aMatch )
         IF Left( aMatch[i, 1, 1], 2 ) == "</"
            ? "Closing tag:", aMatch[i, 1, 1], ;
                    "Start:", aMatch[i, 1, 2], ;
                      "End:", aMatch[i, 1, 3]
         ELSE
            nStart := aMatch[i, 1, 2]
            nEnd   := At( ">", cText, aMatch[i, 1, 3] )

            ? "Opening tag:", SubStr( cText, nStart, nEnd-nStart+1 ), ;
                    "Start:", nStart, ;
                     "End:" , nEnd
         ENDIF
      NEXT
   RETURN