diff options
| -rw-r--r-- | doc/src/sgml/cube.sgml | 187 |
1 files changed, 128 insertions, 59 deletions
diff --git a/doc/src/sgml/cube.sgml b/doc/src/sgml/cube.sgml index 4a093706e4a..1ffc40f1a5b 100644 --- a/doc/src/sgml/cube.sgml +++ b/doc/src/sgml/cube.sgml @@ -25,6 +25,13 @@ <table id="cube-repr-table"> <title>Cube External Representations</title> <tgroup cols="2"> + <thead> + <row> + <entry>External Syntax</entry> + <entry>Meaning</entry> + </row> + </thead> + <tbody> <row> <entry><literal><replaceable>x</></literal></entry> @@ -80,7 +87,8 @@ </para> <para> - White space is ignored, so <literal>[(<replaceable>x</>),(<replaceable>y</>)]</literal> is the same as + White space is ignored on input, so + <literal>[(<replaceable>x</>),(<replaceable>y</>)]</literal> is the same as <literal>[ ( <replaceable>x</> ), ( <replaceable>y</> ) ]</literal>. </para> </sect2> @@ -98,11 +106,11 @@ <title>Usage</title> <para> - <xref linkend="cube-operators"> shows the operators provided for type - <type>cube</>. + <xref linkend="cube-operators-table"> shows the operators provided for + type <type>cube</>. </para> - <table id="cube-operators"> + <table id="cube-operators-table"> <title>Cube Operators</title> <tgroup cols="3"> <thead> @@ -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: <programlisting> -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; </programlisting> </para> @@ -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: <programlisting> -SELECT c FROM test ORDER BY c ~> 1 LIMIT 5; +SELECT c FROM test ORDER BY c ~> 1 LIMIT 5; </programlisting> And to get 2-D cubes ordered by the first coordinate of the upper right corner descending: <programlisting> -SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5; +SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5; </programlisting> </para> @@ -267,128 +273,191 @@ SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5; <table id="cube-functions-table"> <title>Cube Functions</title> - <tgroup cols="2"> + <tgroup cols="4"> + <thead> + <row> + <entry>Function</entry> + <entry>Result</entry> + <entry>Description</entry> + <entry>Example</entry> + </row> + </thead> + <tbody> <row> - <entry><literal>cube(float8) returns cube</literal></entry> + <entry><literal>cube(float8)</literal></entry> + <entry><type>cube</type></entry> <entry>Makes a one dimensional cube with both coordinates the same. + </entry> + <entry> <literal>cube(1) == '(1)'</literal> </entry> </row> <row> - <entry><literal>cube(float8, float8) returns cube</literal></entry> + <entry><literal>cube(float8, float8)</literal></entry> + <entry><type>cube</type></entry> <entry>Makes a one dimensional cube. + </entry> + <entry> <literal>cube(1,2) == '(1),(2)'</literal> </entry> </row> <row> - <entry><literal>cube(float8[]) returns cube</literal></entry> + <entry><literal>cube(float8[])</literal></entry> + <entry><type>cube</type></entry> <entry>Makes a zero-volume cube using the coordinates defined by the array. + </entry> + <entry> <literal>cube(ARRAY[1,2]) == '(1,2)'</literal> </entry> </row> <row> - <entry><literal>cube(float8[], float8[]) returns cube</literal></entry> + <entry><literal>cube(float8[], float8[])</literal></entry> + <entry><type>cube</type></entry> <entry>Makes a cube with upper right and lower left coordinates as defined by the two arrays, which must be of the same length. - <literal>cube('{1,2}'::float[], '{3,4}'::float[]) == '(1,2),(3,4)' + </entry> + <entry> + <literal>cube(ARRAY[1,2], ARRAY[3,4]) == '(1,2),(3,4)' </literal> </entry> </row> <row> - <entry><literal>cube(cube, float8) returns cube</literal></entry> - <entry>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. - <literal>cube('(1)',2) == '(1,2),(1,2)'</literal> + <entry><literal>cube(cube, float8)</literal></entry> + <entry><type>cube</type></entry> + <entry>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. + </entry> + <entry> + <literal>cube('(1,2),(3,4)'::cube, 5) == '(1,2,5),(3,4,5)'</literal> </entry> </row> <row> - <entry><literal>cube(cube, float8, float8) returns cube</literal></entry> - <entry>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. <literal>cube('(1,2)',3,4) == '(1,3),(2,4)'</literal> + <entry><literal>cube(cube, float8, float8)</literal></entry> + <entry><type>cube</type></entry> + <entry>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. + </entry> + <entry> + <literal>cube('(1,2),(3,4)'::cube, 5, 6) == '(1,2,5),(3,4,6)'</literal> </entry> </row> <row> - <entry><literal>cube_dim(cube) returns int</literal></entry> - <entry>Returns the number of dimensions of the cube + <entry><literal>cube_dim(cube)</literal></entry> + <entry><type>integer</type></entry> + <entry>Returns the number of dimensions of the cube. + </entry> + <entry> + <literal>cube_dim('(1,2),(3,4)') == '2'</literal> </entry> </row> <row> - <entry><literal>cube_ll_coord(cube, int) returns double </literal></entry> - <entry>Returns the n'th coordinate value for the lower left - corner of a cube + <entry><literal>cube_ll_coord(cube, integer)</literal></entry> + <entry><type>float8</type></entry> + <entry>Returns the <replaceable>n</>-th coordinate value for the lower + left corner of the cube. + </entry> + <entry> + <literal>cube_ll_coord('(1,2),(3,4)', 2) == '2'</literal> </entry> </row> <row> - <entry><literal>cube_ur_coord(cube, int) returns double - </literal></entry> - <entry>Returns the n'th coordinate value for the - upper right corner of a cube + <entry><literal>cube_ur_coord(cube, integer)</literal></entry> + <entry><type>float8</type></entry> + <entry>Returns the <replaceable>n</>-th coordinate value for the + upper right corner of the cube. + </entry> + <entry> + <literal>cube_ur_coord('(1,2),(3,4)', 2) == '4'</literal> </entry> </row> <row> - <entry><literal>cube_is_point(cube) returns bool</literal></entry> - <entry>Returns true if a cube is a point, that is, + <entry><literal>cube_is_point(cube)</literal></entry> + <entry><type>boolean</type></entry> + <entry>Returns true if the cube is a point, that is, the two defining corners are the same.</entry> + <entry> + </entry> </row> <row> - <entry><literal>cube_distance(cube, cube) returns double</literal></entry> + <entry><literal>cube_distance(cube, cube)</literal></entry> + <entry><type>float8</type></entry> <entry>Returns the distance between two cubes. If both cubes are points, this is the normal distance function. </entry> + <entry> + </entry> </row> <row> - <entry><literal>cube_subset(cube, int[]) returns cube - </literal></entry> + <entry><literal>cube_subset(cube, integer[])</literal></entry> + <entry><type>cube</type></entry> <entry>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. - <literal>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. - <literal>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. + </entry> + <entry> + <literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2]) == '(3),(7)'</> + <literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1]) == + '(5,3,1,1),(8,7,6,6)'</> </entry> </row> <row> - <entry><literal>cube_union(cube, cube) returns cube</literal></entry> - <entry>Produces the union of two cubes + <entry><literal>cube_union(cube, cube)</literal></entry> + <entry><type>cube</type></entry> + <entry>Produces the union of two cubes. + </entry> + <entry> </entry> </row> <row> - <entry><literal>cube_inter(cube, cube) returns cube</literal></entry> - <entry>Produces the intersection of two cubes + <entry><literal>cube_inter(cube, cube)</literal></entry> + <entry><type>cube</type></entry> + <entry>Produces the intersection of two cubes. + </entry> + <entry> </entry> </row> <row> - <entry><literal>cube_enlarge(cube c, double r, int n) returns cube</literal></entry> - <entry>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. + <entry><literal>cube_enlarge(c cube, r double, n integer)</literal></entry> + <entry><type>cube</type></entry> + <entry>Increases the size of the cube by the specified + radius <replaceable>r</> in at least <replaceable>n</> dimensions. + If the radius is negative the cube is shrunk instead. + All defined dimensions are changed by the radius <replaceable>r</>. + Lower-left coordinates are decreased by <replaceable>r</> and + upper-right coordinates are increased by <replaceable>r</>. If a + lower-left coordinate is increased to more than the corresponding + upper-right coordinate (this can only happen when <replaceable>r</> + < 0) than both coordinates are set to their average. + If <replaceable>n</> is greater than the number of defined dimensions + and the cube is being enlarged (<replaceable>r</> > 0), then extra + dimensions are added to make <replaceable>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. + </entry> + <entry> + <literal>cube_enlarge('(1,2),(3,4)', 0.5, 3) == + '(0.5,1.5,-0.5),(3.5,4.5,0.5)'</> </entry> </row> </tbody> |