Collection Expressions

OQL introduces a few operators for object collection manipulation: one of them is the array deferencing operator ``[]'' (5.15) that is overloaded for ordered collection manipulation.
Some them are ODMG OQL compliant, the others are EYEDB extensions. Object collections may be persistent or transient, orderered or not. These operators allows us to make the following kind of operations:

1. gets the contents of a collection: operator contents,
2. get an element at a given position in an ordered collection: operator [] (ODMG compliant),
3. get elements at some given positions in an ordered collection: operators [:] (ODMG compliant) and [?],
4. checks if an element is in a collection: operator in (ODMG compliant),
5. add an element in an unordered collection: operator add/to
6. suppress an element from an unordered collection: operator suppress/from,
7. set or suppress an element in an ordered at a given position: operator [],
8. set or suppress elements in an ordered at a given position: operators [:] and [?],
9. append an element in an ordered collection: operator append/to,
10. checks if a given condition is realized for at least one element in a collection: operator in (ODMG compliant),
11. checks if a given condition is realized for all elements in a collection: operator for/all (ODMG compliant),
12. checks if a given condition is realized for a given number range of elements in a collection: operator extended for.

In all the following examples, the OQL variables p0 denotes the first Person instance in the database: p0 := first(select Person).

Important Note: although they are reference in the following descriptions of collection operators, the object collections list are not implemented in the current version of EYEDB.

contents Operator

The contents unary operator is used to give the contents of a given ordered or unordered object collection. It returned an OQL collection of the same type of the object collection: set, bag, array or list.

General Information
Operator	contents
Syntax	contents expr
Type	unary
Operand Types	oid or object collection
Result Type	a collection of objects
Functions	returns the contents of an object collection

Expression Examples
contents(p0.children)	an array of Person oids
select contents(x.children) from Person x	returns a list of arrays of Person oids.
contents(list(1, 2, 3))	raises an error: oid or object expected, got list

in Operator

The in operator is used to check if a given element is in ordered or unordered object collection.

General Information
Operator	in
Syntax	expr in expr
Type	binary
Operand Types	first operand: any type, second operand: oid or object collection
Result Type	boolean
Functions	returns true if the first operand belongs to the collection pointed by the second operand; false otherwise

Expression Examples
first(select Person.name = NULL) in p0.children	returns true if the first Person instance whose name is unitialized is in the array of children of the first Person
first(select Car.brand = "renault") in p0.cars	returns true if the first Car instance whose brand equals renault is in the set of cars of the first Person

add/to Operator

The add/to operator is used to add an element in an unordered collection (set or bag).

General Information
Operator	add/to
Syntaxes	add expr to expr
Type	binary
Operand Types	first operand: any type, second operand: oid or object unorderered collection (set or bag)
Result Type	type of the first operand
Functions	adds the first operand to the non-indexed collection (i.e. bag or set) pointed by the second operand; returns the first operand.

Expression Examples
add new Car(num : 100) to p0.cars	returns the created Car oid
add new Person(name : "john") to p0.children	raises an error: cannot used non indexed insertion in an array
add new Car() to new set<Car *>()	returns the just created car; but we have lost the oid of the just created set of cars!
add new Person() to (c := new bag<Person *>())	returns the just created person; the created bag has been kept in the OQL variable c

[] Operator

The polymorphic [] operator is used to set or get an element in an ordered collection (array or list) at a given position: it can be used in a right or left value.

General Information
Operator	[]
Syntaxes	expr [ expr ]
Type	binary
Operand Types	first operand: collection array or list, second operand: integer
Result Type	the type of the element,
Functions	gets the element in the collection pointed by the first operand at the position pointed by the second operarand. If used at a left value, gets a reference to that element.

Expression Examples
p0.children[0]	returns the child at position #0 in p0.children collection. Returns nil if there is no child at this position
p0.children[0] := Person(name : "john")	returns the created Person oid
p0.children[12039] := Person(name : "henry")	returns the created Person oid. This expression is valid in any cas as the collection arrays automatically increased its size
(array<Person *>())[0] := new Car(num : 100)	returns the just created person; but the created array has been ``lost'' as it is not tied to any instance and as we did not bind it to any OQL variable
(c := array<Person *>())[0] := new Car(num : 100)	returns the just created person; the created array has been kept in the OQL variable c
p0.cars[1] := Car(num : 100)	raises an error: array expected, got set

[:] Operator

The polymorphic [:] operator is used to set or get some elements in an ordered collection (array or list) at some given positions: it can be used in a right or left value. When used in a right value, the returned atom is a set of struct with the two attributes index and value. In each struct element returned, the value of index is the position of the element, the value of value is the element value. Note the returned struct elements are not ordered according to the element postions; it is why a set is returned. When used as a left value, the returned atom is a set of references on the elements .

General Information
Operator	[:]
Syntaxes	expr [ expr : expr ]
Type	ternary
Operand Types	first operand: collection array or list, second and third operands: integer
Result Type	the type of the element,
Functions	gets the elements in the collection pointed by the first operand at the position range pointed by the second and third operarands. If used at a left value, gets references to that elements.

Expression Examples
p0.children[0:1]	returns a set of struct including the children and the position of the children position #0 and #1 in the p0.children collection. For instance: set(struct(index : 0, value : 3874.33.293847:oid), struct(index : 1, value : 2938.33.1928394:oid))
Returns nil if there is no child at these positions
p0.children[0:4] := Person(name : "john")	Sets all the children at the position #0 to #4 to a new Person instance.
returns the created Person oid
p0.children[12000:12039] := Person(name : "henry")	returns the created Person oid. This expression is valid in any cas as the collection arrays automatically increased its size
(array<Person *>(list(Person())))[0]	returns the just created person within the just created array. But the array is ``lost'' as it is not tied to any instance and as we did not bind it to any OQL variable
(x := array<Person *>(list(Person())))[0]	returns the just created person; the created array has been kept in the OQL variable c

[?] Operator

The polymorphic [?] operator is used to set or get all the elements in an ordered collection (array or list). It can be used in a right or left value. When used in a right value, the returned atom is a set of struct with the two attributes index and value. In each struct element returned, the value of index is the position of the element, the value of value is the element value. Note the returned struct elements are not ordered according to the element postions; it is why a set is returned.
When used as a left value, the returned atom is a set of references on the elements .

General Information
Operator	[?]
Syntaxes	expr [?]
Type	unary
Operand Type	collection array or list,
Result Type	a set of struct or a set of references
Functions	gets all the elements in the collection pointed by the first operand If used at a left value, gets references to that elements.

Expression Examples
p0.children[?]	returns a set of struct including the children and the position of all the children in the p0.children collection. For instance: set(struct(index : 0, value : 3874.33.293847:oid), struct(index : 1, value : 2938.33.1928394:oid))
Returns nil if the collection is empty
p0.children[?] := Person(name : "john")	Sets all the children to a new Person instance.
returns the created Person oid
(array<Person *>(list(Person(), Person())))[?]	returns a set of struct including the just created Person instances in the just created array.

append/to Operator

The append/to operator is used to append an element to an ordered collection (list or array).

General Information
Operator	append
Syntaxes	append expr to expr
Type	binary
Operand Types	first operand: any type, second operand: oid or object denoting an ordered collection
Result Type	any type
Functions	appends the element denoted by the first operand to the indexed collection (i.e. list or array) denoted by the second operand.

Expression Examples
append Person() to p0.children	the created Person instance
append Car()to p0.cars	raises an error: array or list expected, got set<Person*>

suppress/from Operator

The suppress/from operator is used to suppress an element from an ordered collection (set or bag).

General Information
Operator	suppress/from
Syntaxes	suppress expr from expr
Type	binary
Operand Types	first operand: any type, second operand: oid or object collection
Result Type	type of the first operand
Functions	suppress the first operand from the non-indexed collection (i.e. bag or set) pointed by the second operand; returns the first operand.

Expression Examples
suppress (select Car.num = 1000) from p0.cars	the suppressed car if it was found in the collection; otherwise, raises an error
suppress new Car() from p.cars	raises an error: item '71238.13.3959935:oid' not found in collection
suppress p0 from p0.children	raises an error: cannot used non indexed suppression in an array

empty Operator

The empty operator is used to empty an ordered or an unordered collection.

General Information
Operator	empty
Syntax	empty expr
Type	unary
Operand Types	oid or object collection
Result Type	nil
Functions	empty the collection pointed by the operand

Expression Examples
empty(first (select Person).children)	nil
empty(first (select Person).cars)	nil
empty new set<Car *>(list(new Car()))	nil; this expression creates a collection of Car containing initially a new Car, and empty it!

in Operator

The in operator is used to check if a given condition is realized for at least one element in an ordered or unordered collection.

General Information
Operator	in
Syntax	identifier in expr : expr
Type	ternary
Operand Types	first operand: identifier, second operand: oid or object collection, third operand: boolean
Result Type	boolean
Functions	returns true if it exists in the collection pointed by the second operand an element for which the third operand is evaluated to true.

Expression Examples
x in p0.children: x.name = "mary"	true or false
x in p0.cars: x.num < 100 and x.num >= 90	true or false

for Operator

The for/all operator is used to check if a given condition is realized for all elements in an ordered or unordered collection. This operator is ODMG compliant.

General Information
Operator	for/all
Syntaxes	for all identifier in expr : expr
Type	ternary
Operand Types	first operand: identifier, second operand: oid or object collection, third operand: boolean
Result Type	boolean
Functions	returns true if for all items contained in the collection pointed by the second operand the third operand is evaluated to true.

Expression Examples
for all x in p0.children: x.name == "john"	true or false
for all x in p0.cars: x.num % 10	true or false

The for/cardinality operator is used to check if a given condition is realized for a given number range of elements in an orderer or unordered collection. Note that this operator is the generalisation of the in and for/all operators:
for <0:$> is equivalent to in
for <$> is equivalent to for all

General Information
Operator	forcardinality
Syntaxes	for < expr : expr > identifier in expr : expr
	for < expr > identifier in expr : expr
Type	5-ary
Operand Types	first and optional second operands: integer or $, where $ denotes the collection cardinality, third operand: oid or object, fourth operand: identifier, fifth operand: boolean
Result Type	boolean
Functions	returns true if the number of items in the collection pointed by the third operand for which the third operand is evaluated to true is in the interval [first operand, second operand].

Expression Examples
for <0:4> x in p0.children: x.name == "john"	true if at most 4 children have their name equals to john
for <4> x in p0.children: x.name == "john"	true if one an only one children have its name equals to john
for <0:$> x in p0.cars: x.num = 10	equivalent to in
for <$> x in p0.cars: x.num = 10	equivalent to for/all