Click or drag to resize

IMcOMGlobalMcSearchString Method

This function searches a string to find the first occurrence of a sub-string which matches a supplied template string. Alternatively, an option checks for a match between the template and the whole string; used this way, SearchString is a test for equivalent strings.

Namespace:  MediaCy.IQL.ObjectManager
Assembly:  MediaCy.IQL.ObjectManager (in MediaCy.IQL.ObjectManager.dll) Version: 10.0.6912.0
Syntax
VB
Copy
Function McSearchString ( 
	Template As String,
	StringToSearch As String,
	Optional OptionFlags As mcobjTextMatchFlags = mcobjTextMatchFlags.mcobjNoRegExprAndMatchCase,
	<OptionalAttribute> CharLimits As Object
) As McObject

Parameters

Template
Type: SystemString
StringToSearch
Type: SystemString
The string being searched
OptionFlags (Optional)
Type: MediaCy.IQL.ObjectManagermcobjTextMatchFlags
Flags to control whether the TemplateString is to be interpreted as a regular expression or not, and whether case should be ignored in the lookup. Flags also control whether the whole string must be matched, and if a regular expression template needs to match a word or if wild card regular expressions are allowed to extend across an end-of-line in the StringToSearch.
CharLimits (Optional)
Type: SystemObject
If given, a length-1 or length-2 array. The first element is an offset into StringToSearch giving the starting point of the search. If the array is length-2, then then second element is the maximum number of characters to search (if this element is not given, the StringToSearch is potentially searched up to its end). A negative offset or count results in a no-match return value. If not given, no offset or character limits are used; searching starts at offset 0, the beginning of the StringToSearch and can cover the whole string, if necessary.

Return Value

Type: McObject
An Long array of length-2 or longer. If no match is is found, both values will be negative. If a sub-string is found, the first value is the positive index into StringToSearch of the character that matched the beginning of the template; the second value is the number of characters in the matching substring (for certain regular expressions, the number of matching characters can be zero; e.g., ^$ matches zero-length lines). If the regular expression contained groups (i.e., '\(' and '\)' pairs), then for each group found, the starting offset and count (which can be zero) of the grouped characters are appended.
Remarks
If a match is found, a length-2 results vector is returned indicating where the matched sub-string starts and how long it is. The template string can optionally contain a "regular-expression" similar to that used by the UNIX grep utility. If the "enable regular expression" option is selected, the template string can contain special wild card characters according to the following rules: . A dot (period) matches any single character. the brackets. The brackets may contain ranges; for example, [a-z] matches any letter from a through z (A through Z will also match if the "ignore case" option is selected). character, matches any character not listed within the brackets. The brackets may contain ranges; for example, [^a-z] matches any character other than a lower case letter (upper case letters will also fail to match if the "ignore case" option is selected). * The character or any one of a bracketed group of characters preceding a * character is matched zero or more times. ^ and $ match the beginning of a line (following a line-feed character, \n) or end-of-line (a carriage-return \r, a \n, or end of row), respectively. < and > match the beginning or end of a word, respectively (a word consists of letters, numbers or underscore only). A group may be identified by surrounding the group with \( and \). The backslash, \, is the escape character; it undoes the special meanings of the above characters. Since the backslash is also ALI's escape character, you will need to put in \\ pairs to get one backslash within a quoted string. Any other character matches only that character.
Note Note
The UNIX grep utility uses \< and \> instead of < and > for begin/end word in regular expressions. Currently, we do not support the grep group-reference construct \digit within reqular expression templates.
Examples
VB
Copy
'This module is SearchStringOrListSamples.bas
'It has VB samples for using the McOMGlobal methods
'McSearchString and McLookupInList

Option Explicit

Sub TestForEquivalentString()
    Dim strText As String
    strText = InputBox("Enter your name:")
    ' Test for equal strings, ignoring case.
    If McSearchString("mary", strText, mcobjMatchEntireString Or mcobjIgnoreCase)(0) >= 0 Then
        MsgBox "Hello Mary!" 'if equal
    Else 'no match
        MsgBox "You aren't Mary."
    End If
End Sub 'TestForEquivalentString

Sub FindWordsStartingWithT()
    Output.Show "Output"
    Output.Clear
    Dim strToTest As String, strResultsList() As String
    strToTest = "This is a test."
    Dim bMore As Boolean, iOffset As Long, nFound As Long
    iOffset = 0
    bMore = True
    Do
        Dim iFound() As Long
        iFound = McSearchString("t.*", strToTest, _
            mcobjAllowRegularExpression Or mcobjMatchWholeWords Or mcobjIgnoreCase, iOffset)
        bMore = iFound(0) >= 0
        If bMore Then
            'extract the found text
            Dim selFound As McObject
            Set selFound = McOpFillIn(iFound(0), iFound(0) + iFound(1))
            Dim strFound As String
            strFound = McOpSelect(strToTest, selFound)
            'ReDim Preserve strResultsList(nFound) As String
            'strResultsList(nFound) = strFound 'append the found word to the results
            'below does the same as the above two lines
            strResultsList = McOpConcatConcat(strResultsList, strFound)
            nFound = nFound + 1
            iOffset = iFound(0) + iFound(1) 'Start next search past this one
        End If
    Loop While bMore
    Output.PrintMessage "In the string """ + strToTest + """" + vbCrlf + _
        "We found " & nFound & " words that start with T:" & vbCrlf & McToText(strResultsList)
End Sub 'FindWordsStartingWithT

Sub LookupNamesInList()
    Output.Show "Output"
    Output.Clear
    ' Pick names starting with S or C from a list of names
    Dim varNames As Variant
    varNames = Array("Sally", "George", "Carl", "Bill", "Sam")
    Output.PrintMessage "List of names:" + vbCrlf + McToText(varNames)

    ' do the lookup, allowing regular expressions and ignoring case
    Dim selFound() As Long
    selFound = McLookupInList("[sc].*", varNames, mcobjAllowRegularExpression + mcobjIgnoreCase)
    Output.PrintMessage "You found these names starting with S or C: " & vbCrlf & _
        McToText(McOpSelect(varNames, selFound))
    Output.PrintMessage "You ignored these names: " & vbCrlf & _
        McToText(McOpSelect(varNames, McOpNOT(selFound)))
End Sub 'LookupNamesInList
See Also