IFeatureClass.Search Method

Returns an object cursor that can be used to fetch feature objects selected by the specified query.

[Visual Basic .NET]
Public Function Search ( _
    ByVal filter As IQueryFilter, _
    ByVal Recycling As Boolean _
) As IFeatureCursor

[C#]
public IFeatureCursor Search (
    IQueryFilter filter,
    bool Recycling
);

[C++]
HRESULT Search(
  IQueryFilter* filter,
  VARIANT_BOOL Recycling,
  IFeatureCursor** Cursor
);

[C++]
Parameters
filter [in]
  filter is a parameter of type IQueryFilter
Recycling [in]
  Recycling is a parameter of type VARIANT_BOOL
Cursor [out, retval]
  Cursor is a parameter of type IFeatureCursor

Product Availability

Remarks

Search will return an IFeatureCursor with all of the features that satisfy the attribute and/or spatial constraints as specified by an IQueryFilter reference. If a null value is passed to the filter parameter, the feature cursor will return all of the features from the feature class.

The recycling parameter controls row object allocation behavior. Recycling cursors rehydrate a single feature object on each fetch and can be used to optimize read-only access, for example, when drawing. It is illegal to maintain a reference on a feature object returned by a recycling cursor across multiple calls to NextFeature on the cursor. Features returned by a recycling cursor should not be modified. Non-recycling cursors return a separate feature object on each fetch. The features returned by a non-recycling cursor may be modified and stored with polymorphic behavior.

The Geodatabase guarantees "unique instance semantics" on non-recycling feature objects fetched during an edit session. In other words, if the feature retrieved by a search cursor has already been instantiated and is being referenced by the calling application, then a reference to the existing feature object is returned.

Non-recycling feature cursors returned from the Search method *MUST* be used when copying features from the cursor into an insert cursor of another class.  This is because a recycling cursor reuses the same geometry and under some circumstances all of the features inserted into the insert cursor may have the same geometry.  Using a non-recycling cursor ensures that each geometry is unique.

Existing rows can be edited with either a search cursor or an update cursor. When using a search cursor, NextRow is called, returning a reference to a row. The row is edited, and IRow.Store is called. When using an update cursor, NextRow is called, the row is edited, and ICursor.UpdateRow is called with the row as a parameter. It is important to remember, when using an update cursor, do not call the Store method.

See Also

IFeatureClass Interface | IQueryFilter Interface