location

<Default Package>
Type location

A scalar value representing point or area locations.

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) ...

Locations can be parsed, routed and compared. They are not cyclic.

Field summary
`float`	`x1` The x component of the first point.
`float`	`y1` The y component of the first point.
`float`	`x2` The x component of the second point.
`float`	`y2` The y component of the second point.

Action summary
`boolean`	`static` `canParse(string s)` Check if the string argument can be successfully parsed as a location.
`location`	`static` `parse(string s)` Parse a string as a location.
`location`	`clone()` Create a copy of this location.
`location`	`expand(float size)` Return a new location from this location expanded by the specified amount.
`integer`	`hash()` Get an integer hash representation of the underlying object.
`boolean`	`inside(location enclosing)` Check whether this location is entirely within another location.
`string`	`toString()` Return the string form of this location.

Field detail

x1

float x1

The x component of the first point.

x2

float x2

The x component of the second point.

y1

float y1

The y component of the first point.

y2

float y2

The y component of the second point.

Action detail

canParse

boolean static canParse(string s)

Check if the string argument can be successfully parsed as a location.

Parameters:: s - The string to test for parseability.

Returns:: True if the string could be parsed as a location, false otherwise.

See Also:: location.parse() - See the parse method for how locations are parsed.

parse

location static parse(string s)

Parse a string as a location.

The string form of a location is "location(" X1 "," Y1 "," X2 "," Y2 ")" where X1, Y1, X2 and Y2 are the string forms of the respective float members.

Parameters:: s - The string to parse.

Returns:: The location corresponding to this string.

Throws:: Throws ParseException if the string cannot be parsed as a location.

See Also:: location.canParse() - Use canParse to test whether a string can be parsed without throwing an exception.

clone

location clone()

Create a copy of this location.

Returns:: A copy of this location.

expand

location expand(float size)

Return a new location from this location expanded by the specified amount.

Expand this location by size in all dimensions. If you start with a point location, the return value will be a square 2*size on each side, centered on the original point.

If size is negative, then this method will reduce the size of this location by the specified amount.

Parameters:: size - The amount to add to each point.

Returns:: A new location expanded or contracted by the specified amount.

hash

integer hash()

Get an integer hash representation of the underlying object.

This function will return an integer evenly distributed over the whole range suitable for partitioning or indexing of that structure. Multiple different object can resolve to the same hash value.

Returns:: An integer respresentation of the underlying object.

inside

boolean inside(location enclosing)

Check whether this location is entirely within another location.

Parameters:: enclosing - The location to check whether this location is inside.

Returns:: True if this location is entirely within enclosing, false otherwise.

toString

string toString()

Return the string form of this location.

The return value of this method can be parsed by the parse() method.

Returns:: The string form of this location.

See Also:: location.parse() - See the parse method for the string form of locations.

<Default Package>Type location

x1

x2

y1

y2