xHarbour Reference Documentation > Function Reference

HB_AtX()

Locates a substring within a character string based on a regular expression.

Syntax

HB_AtX( <cRegEx>         , ;
        <cString>        , ;
       [<lCaseSensitive>], ;
       [@<nStart>]       , ;
       [@<nLen>]           ) --> cFoundString

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 matching substring.

<lCaseSensitive>

This parameter defaults to .T. (true) so that a case sensitive search is performed. Passing .F. (false) results in a case insensitive search.

@<nStart>

If passed by reference, <nStart> gets assigned a numeric value indicating the start position of the found substring in <cString>. When there is no match, <nStart> is set to zero.

@<nLen>

If passed by reference, <nLen> gets assigned a numeric value indicating the length of the found substring in <cString>. When there is no match, <nLen> is set to zero.

Return

The function returns the first substring contained in <cString> that matches the regular expression <cRegEx>. If no match is found, the return value is NIL.

Description

Function HB_AtX() searches a character string for matching regular expression and returns the found substring. It is a simple pattern matching function which searches and extracts only the first occurance of a substring and optionally returns its position and size in the searched string when <nStart> and <nLen> are passed by reference.

Info

See also:	At(), HB_RegEx(), HB_RegExAll(), HB_RegExSplit(), RAt(), SubStr()
Category:	Character functions , Regular expressions , xHarbour extensions
Source:	rtl\regex.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example extracts an eMail address from a text string.
// The search is case insensitive although the RegEx defines
// character classes only with upper case letters.

   PROCEDURE Main
      LOCAL cRegEx := "[A-Z0-9._%-]+@[A-Z0-9.-]+\.[A-Z]{2,4}"
      LOCAL cText  := "Send your request to info@xharbour.com " + ;
                      "for more information"
      LOCAL cEmail, nStart, nLen

      cEmail := HB_AtX( cRegEx, cText, .F., @nStart, @nLen )

      ? cEmail        // result: info@xharbour.com
      ? nStart        // result: 22
      ? nLen          // result: 17
   RETURN