The 1.3.0 API doc for the following methods leaves the case of non-intersecting rectangles undocumented. The documentation should be changed to state that the behavior is undefined or to describe the existing behavior.

Rectangle.intersection()
Rectangle.createIntersection()
Rectangle2D.createIntersection()
Rectangle2D.Double.createIntersection()
Rectangle2D.Float.createIntersection()

Please document this behavior. I offer two suggestions:

1) document the return value as "undefined" for calling these methods on non-intersecting rectangles,

2) Describe the current behavior when applied to non-intersecting rectangles.

In either case, I'd ask for the doc to advise the use of the Rectangle.intersects method and its analogues before calling these methods, if the programmer wants a meaningful result.

From my limited testing it appears that the methods return the rectangle defined by the diagonal between the two source rectangles. For example.

Given two rectangles:

left,upper left,upper width,height
50,50 70,70 20,20

100,100 200,200 100,100

Rectangle2D.createIntersection returns the rectangle defined by

left,upper left,upper width,height
70.70 100,100 30,30

This is clearly not the documented behavior:

the largest Rectangle2D contained in both the specified
Rectangle2D and in this Rectangle2D.



I have attached a test program that calls Rectangle2D.createIntersection, and reports the result. It also draws the two rectangles, as an aid to understanding.

javac testIntersection.java

java testIntersection -usage
Usage: testIntersection <x1> <y1> <width1> <height1> <x2> <y2> <width2> <height2>

java testIntersection
paint()
R1: (50,50,20,20)
R2: (100,100,100,100)
r1 and r2 don't intersect, so here's the zany result
intersect: (70,70,30,30)
union: (50,50,150,150)
paint()


tom.gould@east 2000-09-27

Name: yyT116575 Date: 11/06/2000


java version "1.3.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.0-C)
Java HotSpot(TM) Client VM (build 1.3.0-C, mixed mode)


The Rectangle2D.createIntersection method returns incorrect results when either
rectangle involved in the operation has negative coordinates.

The following source code exhibits the behavior:

import java.awt.geom.*;


public class RectangleXSect {

public static final void main (String [] args)
{
Rectangle2D rect1 = new Rectangle2D.Double(-100, -100, 50, 50);
System.out.println("Rect 1 : " + rect1);

Rectangle2D rect2 = new Rectangle2D.Double(100, 100, 50, 50);
System.out.println("Rect 2 : " + rect2);

Rectangle2D x1 = rect1.createIntersection(rect2);
System.out.println("Intersection -- minX, minY: " + x1.getX() +", " + x1.getY());
System.out.println("Intersection -- w, h: " + x1.getWidth() + "," + x1.getHeight());
System.out.println("Intersection -- is empty: " + x1.isEmpty());

Rectangle2D x2 = rect2.createIntersection(rect1);
System.out.println("Intersection -- minX, minY: " + x2.getX() +", " + x2.getY());
System.out.println("Intersection -- w, h: " + x2.getWidth() + "," + x2.getHeight());
System.out.println("Intersection -- is empty: " + x2.isEmpty());

}

}


The program output is:
Rect 1 : java.awt.geom.Rectangle2D$Double[x=-100.0,y=-100.0,w=50.0,h=50.0]
Rect 2 : java.awt.geom.Rectangle2D$Double[x=100.0,y=100.0,w=50.0,h=50.0]
Intersection -- minX, minY: -50.0, -50.0
Intersection -- w, h: 150.0, 150.0
Intersection -- is empty: false
Intersection -- minX, minY: -50.0, -50.0
Intersection -- w, h: 150.0, 150.0
Intersection -- is empty: false

--------
The intersection should be an empty rectangle.
(Review ID: 108465)
======================================================================