Property :: first - Try selecting first instance in a collection
The function tries to select the first instance in a property handle (collection). Calling first() for an attribute property will work as well, but without any effect. For attribute arrays it will position the property handle to the first array element.
When a filter has been defined for the collection, the function tries to locate the first valid instance according to the filter condition.
Usually, the instance will be located but not positioned. In case of instance filters or unordered collections, however, instances might be positioned.
The function returns true, when the first instance has been located successfully. Otherwise it returns false. In case of read errors or when the property handle is not accessible, the function throws an exception.
The value is true when the function was executed successfully. Otherwise the value is set to false.
Implementation overview
- Locate first instance
Property :: first ( ) - Locate and read first instance
Property :: first ( bRead )
Implementation details
-
Locate first instance
bool Property :: first ( )
The function locates the first instance in the property handle without reading it. The instance might be selected when a filter has been set for the property handle.
In order to make sure that the instance is selected, one may call get() or first(true).
to list
-
Locate and read first instance
bool Property :: first ( bool bRead )
The function locates and reads the first instance, when passing true in bRead. In this case the property handle is positioned. When passing false, the function tries to locate the instance without reading.
- bRead
- Read option
The option forces the function to read the instance when it could be located.
to list
- bRead
- Read option