Searches for sub-collections with a
given name "in depth" (If the VarDictionary object contains
other VarDictionary objects in its items they will be searched) .
See the details below.Syntax:
Set result = object.FindByValue( name,
value [, first [, maxElements [, depth ]]])
IDL definition:
[id(19), helpstring("method FindByValue")]
HRESULT FindByValue( [in] BSTR bstrName,
[in] BSTR bstrVal,
[in,defaultvalue(1)] long lFirst,
[in,defaultvalue(1)] long lMax,
[in,defaultvalue(-1)] long lDepth,
[out,retval] IDispatch** ppResult);
Parameters:
object - Previously created VarDictionary object
name - String - the item name
value - String - the value of the item name
first - (optional, number) specifies first element found to
be returned (1- based). For example if there are 10 elements with this
name and first is set to 5 - then the first 4 elements will not be
returned. The default value is 1.
maxElement - (optional, number, default is 1) Maximum
elements to return. Search will end when the maxElements are found.
depth - (optional, number, default is -1) If the
VarDictionary is a collection of collections - i.e. some items in the
collection are other VarDictionary objects you could think about the
VarDictictionary object being searched as for a root node in a tree.
depth specifies how deep the search will be. Value of
-1 means unlimited, 0 means - only the current collection, positive
number specifies the maximum levels to be searched.
Returns (result): A collection of the
collections found. Found collections are those that have elements with
names matching the name parameter and their value matches the value
parameter.
Examples:
' Fill some data to prepare the example
Set coll = CreateObject("newobjects.utilctls.VarDictionary")
coll.Add "A", 15
coll.Add "C", coll.CreateNew
coll("C").Add "A", 12
coll("C").Add "B", "Blah"
coll.Add "B", coll.CreateNew
coll("B").Add "X", "Blah"
' We have two subcollections
Set found = coll.FindByValue("B","BLAH",1,100)
Response.Write "Found " & found.Count " items <BR>"
This example will find one item - the sub-collection
"C".
Remarks:
This method returns only sub-collections - i.e. only items that
contain VarDictionaries. The search criteria means "give me the
nodes of the tree which contain items named name and have values value".
This is similar with XML DOM - when searching for nodes with given
attributes and given values.
See also: FindByName
|
