location
Values of the location type describe rectangular areas in a two-dimensional unitless Cartesian coordinate plane. Locations are defined by the float coordinates of two points x1, y1 and x2, y2 at diagonally opposite corners of an enclosing boundary rectangle.
The format of a location type is as follows:
location(x1, y1, x2, y2)
An example of a valid location therefore looks as follows:
location(15.23, 24.234, 19.1232, 28.873)
A point can be represented simply as a rectangle with both corners being the same point. You can access the data members of a location type in the same way that you access the fields of an event. For example:
location l := location(1.0, 2.0, 3.0, 4.0);
print l.x1.toString();
This prints 1.0. You can use a location type to describe a rectangular area but you can also use it to describe various other quantities, such as line segments connecting two endpoints, circles, vectors, or points in a four-dimensional space. However, certain inbuilt methods, such as the inside() method, give correct results only for boundary rectangles.
A listener that is watching for a particular value for a location field matches when it finds a location field that intersects with the location value specified by the listener. In the following example, the listener matches each A event whose loc field specifies a location that intersects with the square defined by (0.0, 0.0, 1.0, 1.0). When the limits specified for a location type are out of order, the correlator correctly orders them before performing a comparison. When locations touch it is considered to be an intersection.
location l := location(0.0, 0.0, 1.0, 1.0);
on all A(loc = l) ...
Methods
The following methods may be called on variables of location type:
LocationMethods
canParse() — returns
true if the string argument can be successfully parsed.
clone() – returns a new
location that is an exact copy of the
location.
expand(float) – returns a new
location expanded by the value of the
float parameter in each direction. For example:
location l := location(0.0, 0.0, 0.0, 0.0);
on all A(loc = l.expand(0.5)) ...
This event listener watches for A events whose loc field specifies a location that intersects with (-0.5, -0.5, 0.5, 0.5).
inside(location) – returns
true if the location is entirely enclosed by the space defined by the
location parameter,
false otherwise. Note that if the two locations are exactly equal, the result of calling the
inside() method is
false.
parse() – method that returns the
location instance represented by the
string argument. You can call this method on the
location type or on an instance of a
location type. The more typical use is to call
parse() directly on the
location type.
The
parse() method takes a single string as its argument. This string must be the string form of a
location object. The string must adhere to the format described in
Deploying and Managing Apama Applications,
Event file format. For example:
location a;
a := location.parse("(15.23, 24.234, 19.1232, 28.873)");
You can specify the parse() method after an expression or type name. If the correlator is unable to parse the string, it is a runtime error and the monitor instance that the EPL is running in terminates.
toString() – returns a
string representation of the
location.
