FindIn
Implementation : Function.
Description : Locates member objects and methods of the object denoted by the
Obj parameter, and according to any search terms, and depth
constraint provided. Optionally, will call a user-defined
function for each member located (denoted by the OnFound
parameter).
Signature : FindIn (Obj[, SearchTerms[, OnFound[, DepthMax[, ClientCallPoint]]]])
Parameters : Obj - Reference to object whose members (and
sub-members, if necessary) are to be searched.
SearchTerms - Optional string, describing in
regular-expression syntax the member-names to
be searched for. Can be null.
OnFound - Optional function reference, that denotes the
user-defined function that should be called
for each member found that (optionally)
conforms to the search-terms supplied. Can be
null.
DepthMax - Optional integer, denoting the maximum depth
to which the object structure should be
searched. Can be null, cannot be negative,
default value is infinity if omitted.
ClientCallPoint - Optional string, useful in debugging
client-code, and which is incorporated into
the contents of the message member of the
JavaScript Error-objects that may be thrown
by FindIn or by the OnFound call-back. Can be
omitted and can be null, but if supplied
should, ideally, denote the point in the
application's code where the call to FindIn
was made.
Returns : The number of members found within the object structure.
Throws : Error object, if - Obj is null or undefined
SearchTerms (if provided) is not a string
OnFound (if provided) does not refer to a function
DepthMax (if provided) is non-numeric
DepthMax (if provided) is negative
Notes :
user_defined.call-back
Implementation : Function.
Description : If supplied to FindIn, is called for each member found that
conforms to the search terms supplied to that function (if
any), and that resides within the depth-limit passed to that
function (if any).
Signature : user-defined ([Obj [, Member[, SearchTerms[, Depth[, ClientCallPoint]]])
Parameters : Obj - Reference to the object in which FindIn
located the member indicated by the value of
Member. Is never null, and never refers to
an object of type 'string'.
Member - Reference to member located by FindIn. Is
never null, and never represents a
specific character within a string.
SearchTerms - String, representing the regular-expression
passed to FindIn (if any). Can be null.
Depth - Integer, denoting the depth within the object
structure that the member was located.
May be null or undefined, cannot be negative.
ClientCallPoint - String, passed to FindIn by that function's
caller. Useful in debugging, may be null or
undefined.
Returns : Boolean - False causes FindIn to cease searching, true
causes FindIn to continue searching.
Throws : Any user-specified type.
Notes : The call-back function is free to do whatever it wishes,
including calling FindIn.
The inconsistencies with string and character types, regarding
the possible values of Obj and Member, are due to an oddity that
surfaces in at least one browser when applying for-in loops to
string-type objects.