Utility components FindByValue
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.


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);


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. 


' 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". 


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

Applies to: VarDictionary

newObjects Copyright 2001-2005 newObjects [ ]