diff --git a/doc/src/sgml/cube.sgml b/doc/src/sgml/cube.sgml index 4a093706e4..1ffc40f1a5 100644 --- a/doc/src/sgml/cube.sgml +++ b/doc/src/sgml/cube.sgml @@ -25,6 +25,13 @@ Cube External Representations + + + External Syntax + Meaning + + + x @@ -80,7 +87,8 @@ - White space is ignored, so [(x),(y)] is the same as + White space is ignored on input, so + [(x),(y)] is the same as [ ( x ), ( y ) ]. @@ -98,11 +106,11 @@ Usage - shows the operators provided for type - cube. + shows the operators provided for + type cube. -
+
Cube Operators @@ -240,9 +248,7 @@ For example, the nearest neighbor of the 3-D point (0.5, 0.5, 0.5) could be found efficiently with: -SELECT c FROM test -ORDER BY cube(array[0.5,0.5,0.5]) <-> c -LIMIT 1; +SELECT c FROM test ORDER BY c <-> cube(array[0.5,0.5,0.5]) LIMIT 1; @@ -252,12 +258,12 @@ LIMIT 1; For example, to get the first few cubes ordered by the first coordinate (lower left corner) ascending one could use the following query: -SELECT c FROM test ORDER BY c ~> 1 LIMIT 5; +SELECT c FROM test ORDER BY c ~> 1 LIMIT 5; And to get 2-D cubes ordered by the first coordinate of the upper right corner descending: -SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5; +SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5; @@ -267,128 +273,191 @@ SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5;
Cube Functions - + + + + Function + Result + Description + Example + + + - cube(float8) returns cube + cube(float8) + cube Makes a one dimensional cube with both coordinates the same. + + cube(1) == '(1)' - cube(float8, float8) returns cube + cube(float8, float8) + cube Makes a one dimensional cube. + + cube(1,2) == '(1),(2)' - cube(float8[]) returns cube + cube(float8[]) + cube Makes a zero-volume cube using the coordinates defined by the array. + + cube(ARRAY[1,2]) == '(1,2)' - cube(float8[], float8[]) returns cube + cube(float8[], float8[]) + cube Makes a cube with upper right and lower left coordinates as defined by the two arrays, which must be of the same length. - cube('{1,2}'::float[], '{3,4}'::float[]) == '(1,2),(3,4)' + + + cube(ARRAY[1,2], ARRAY[3,4]) == '(1,2),(3,4)' - cube(cube, float8) returns cube - Makes a new cube by adding a dimension on to an - existing cube with the same values for both parts of the new coordinate. - This is useful for building cubes piece by piece from calculated values. - cube('(1)',2) == '(1,2),(1,2)' + cube(cube, float8) + cube + Makes a new cube by adding a dimension on to an existing cube, + with the same values for both endpoints of the new coordinate. This + is useful for building cubes piece by piece from calculated values. + + + cube('(1,2),(3,4)'::cube, 5) == '(1,2,5),(3,4,5)' - cube(cube, float8, float8) returns cube - Makes a new cube by adding a dimension on to an - existing cube. This is useful for building cubes piece by piece from - calculated values. cube('(1,2)',3,4) == '(1,3),(2,4)' + cube(cube, float8, float8) + cube + Makes a new cube by adding a dimension on to an existing + cube. This is useful for building cubes piece by piece from calculated + values. + + + cube('(1,2),(3,4)'::cube, 5, 6) == '(1,2,5),(3,4,6)' - cube_dim(cube) returns int - Returns the number of dimensions of the cube + cube_dim(cube) + integer + Returns the number of dimensions of the cube. + + + cube_dim('(1,2),(3,4)') == '2' - cube_ll_coord(cube, int) returns double - Returns the n'th coordinate value for the lower left - corner of a cube + cube_ll_coord(cube, integer) + float8 + Returns the n-th coordinate value for the lower + left corner of the cube. + + + cube_ll_coord('(1,2),(3,4)', 2) == '2' - cube_ur_coord(cube, int) returns double - - Returns the n'th coordinate value for the - upper right corner of a cube + cube_ur_coord(cube, integer) + float8 + Returns the n-th coordinate value for the + upper right corner of the cube. + + + cube_ur_coord('(1,2),(3,4)', 2) == '4' - cube_is_point(cube) returns bool - Returns true if a cube is a point, that is, + cube_is_point(cube) + boolean + Returns true if the cube is a point, that is, the two defining corners are the same. + + - cube_distance(cube, cube) returns double + cube_distance(cube, cube) + float8 Returns the distance between two cubes. If both cubes are points, this is the normal distance function. + + - cube_subset(cube, int[]) returns cube - + cube_subset(cube, integer[]) + cube Makes a new cube from an existing cube, using a list of - dimension indexes from an array. Can be used to find both the LL and UR - coordinates of a single dimension, e.g. - cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2]) = '(3),(7)'. - Or can be used to drop dimensions, or reorder them as desired, e.g. - cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1]) = '(5, 3, - 1, 1),(8, 7, 6, 6)'. + dimension indexes from an array. Can be used to extract the endpoints + of a single dimension, or to drop dimensions, or to reorder them as + desired. + + + cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2]) == '(3),(7)' + cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1]) == + '(5,3,1,1),(8,7,6,6)' - cube_union(cube, cube) returns cube - Produces the union of two cubes + cube_union(cube, cube) + cube + Produces the union of two cubes. + + - cube_inter(cube, cube) returns cube - Produces the intersection of two cubes + cube_inter(cube, cube) + cube + Produces the intersection of two cubes. + + - cube_enlarge(cube c, double r, int n) returns cube - Increases the size of a cube by a specified radius in at least - n dimensions. If the radius is negative the cube is shrunk instead. This - is useful for creating bounding boxes around a point for searching for - nearby points. All defined dimensions are changed by the radius r. - LL coordinates are decreased by r and UR coordinates are increased by r. - If a LL coordinate is increased to larger than the corresponding UR - coordinate (this can only happen when r < 0) than both coordinates - are set to their average. If n is greater than the number of defined - dimensions and the cube is being increased (r >= 0) then 0 is used - as the base for the extra coordinates. + cube_enlarge(c cube, r double, n integer) + cube + Increases the size of the cube by the specified + radius r in at least n dimensions. + If the radius is negative the cube is shrunk instead. + All defined dimensions are changed by the radius r. + Lower-left coordinates are decreased by r and + upper-right coordinates are increased by r. If a + lower-left coordinate is increased to more than the corresponding + upper-right coordinate (this can only happen when r + < 0) than both coordinates are set to their average. + If n is greater than the number of defined dimensions + and the cube is being enlarged (r > 0), then extra + dimensions are added to make n altogether; + 0 is used as the initial value for the extra coordinates. + This function is useful for creating bounding boxes around a point for + searching for nearby points. + + + cube_enlarge('(1,2),(3,4)', 0.5, 3) == + '(0.5,1.5,-0.5),(3.5,4.5,0.5)'