本モジュールは、多次元立体を表すためのcubeデータ型を実装します。
以下にcube型で有効な外部表現を示します。 x、yなどは浮動小数点数を意味します。
表 F-1. Cubeの外部表現
| x | 1次元の点。（または幅ゼロの一次元間隔） |
| (x) | 同上 |
| x1,x2,...,xn | n次元空間の点。 内部的には体積0の立方体として表されます。 |
| (x1,x2,...,xn) | 同上 |
| (x),(y) | xからyまで（またはその逆）の1次元の間隔。 順序は関係ありません。 |
| [(x),(y)] | 同上 |
| (x1,...,xn),(y1,...,yn) | 対角の組み合わせで表されるn次元の立体。 |
| [(x1,...,xn),(y1,...,yn)] | 同上 |
立体の対角の入力順序は関係ありません。 統一的な"左下 — 右上"という内部表現を作成するために必要ならば、cube関数は自動的に値を好感します。
空白文字は無視されます。 このため、[(x),(y)]は[ ( x ), ( y ) ]と同じです。
値は内部的に64ビットの浮動小数点数値として格納されます。 つまり、有効桁が16より大きい数値は切り詰められることを意味します。
cubeモジュールには、cube型の値に対するGiSTインデックス演算子クラスが含まれます。 GiST演算子クラスでサポートされる演算子は以下の通りです。
a = b Same as
立体aと立体bは同じです。
a && b Overlaps
立体aと立体bには重なりがあります。
a @> b Contains
立体aは立体bを含みます。
a <@ b Contained in
立体aは立体bに含まれます。
（PostgreSQL 8.2以前では、含有演算子@>と<@はそれぞれ@と~と呼ばれていました。 これらの名前はまだ利用できますが、廃止予定であり、最終的にはなくなります。 古い名前がコアの幾何データ型が従う規約と反対であることに注意してください。）
標準的なB-Tree演算子も提供されます。 以下に例を示します。
[a, b] < [c, d] Less than [a, b] > [c, d] Greater than
これらの演算子はソート以外の実用的な目的に対して大きな意味を持ちません。 これらの演算子はまず(a)と(c)を比べ、等しければ(b)と(d)を比べます。 論理的にはほとんどの場合優れたソート処理と思えます。 こうした型をORDER BYで使用したい場合に有用です。
以下の関数が利用可能です。
表 F-2. Cubeの関数
| cube(float8) returns cube | 同じ軸をもつ、1次元の立体を作成します。 cube(1) == '(1)' |
| cube(float8, float8) returns cube | 1次元の立体を作成します。 cube(1,2) == '(1),(2)' |
| cube(float8[]) returns cube | 配列で定義される座標を使用した体積0の立体を作成します。 cube(ARRAY[1,2]) == '(1,2)' |
| cube(float8[], float8[]) returns cube | 2つの配列で定義される右上および左下座標を持つ立体を作成します。 配列長は同じでなければなりません。 cube('{1,2}'::float[], '{3,4}'::float[]) == '(1,2),(3,4)' |
| cube(cube, float8) returns cube | 新しい座標の両部分に同一の値をを持たせて、既存の立体に次元を加えた立体を新しく作成します。 これは計算した値で部品を追加しながら立体を構築する場合に有用です。 cube('(1)',2) == '(1,2),(1,2)' |
| cube(cube, float8, float8) returns cube | 既存の立体に次元を加えた立体を新しく作成します。 これは計算した値で部品を追加しながら立体を構築する場合に有用です。 cube('(1,2)',3,4) == '(1,3),(2,4)' |
| cube_dim(cube) returns int | 立体の次元数を返します。 |
| cube_ll_coord(cube, int) returns double | 立体の左下隅のn次座標の値を返します。 |
| cube_ur_coord(cube, int) returns double | 立体の右上隅のn次座標の値を返します。 |
| cube_is_point(cube) returns bool | 立体が点、つまり2つの定義された隅が同一の場合真を返します。 |
| cube_distance(cube, cube) returns double | 2つの立体間の距離を返します。 両方の立体が点の場合、これは通常の距離測定関数です。 |
| cube_subset(cube, int[]) returns cube | 配列内の次元インデックスの一覧を使用して、既存の立体から新しい立体を作成します。 例えば、cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2]) = '(3),(7)'のように1次元のLLおよびLR座標を見つけるために使用することができます。 また、例えば、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 | 2つの立体の和集合を作成します。 |
| cube_inter(cube, cube) returns cube | 2つの立体の共通部分を作成します。 |
| cube_enlarge(cube c, double r, int n) returns cube | 最小でn次元において指定した径で立体のサイズを増加させます。 径が負の場合、立体は縮小されます。 これは、近傍点を見つけるための点を囲む境界矩形を作成する際に有用です。 定義済のすべての次元は径rにより変わります。 LL座標をrにより減少し、UR座標をrにより増加します。 LL座標を対応するUR座標より大きくするために増加する場合（これはr < 0の場合にのみ発生します）、両方の座標はその平均値に設定されます。 nが定義済の次元より多く、かつ、立体が増加される（r >= 0）場合、余計な座標の基として0が使われます。 |
select cube_union('(0,5,2),(2,3,1)', '0');
cube_union
-------------------
(0, 0, 0),(2, 5, 2)
(1 row)この和集合および以下の共通集合は一般常識と矛盾しないと思います。
select cube_inter('(0,-1),(1,1)', '(-2),(2)');
cube_inter
-------------
(0, 0),(1, 0)
(1 row)次元が異なる立体のバイナリ操作すべてにおいて、より低い次元の方がデカルト投影、つまり、文字列表現で省略された座標に0を持つものになると仮定します。 上の例は以下と同じです。
cube_union('(0,5,2),(2,3,1)','(0,0,0),(0,0,0)');
cube_inter('(0,-1),(1,1)','(-2,0),(2,0)');以下の含有の述部は点構文を使用しますが、実際内部的には第2引数は矩形として表されます。 この構文により、別の点用の型や(box,point)という述部用の関数を定義することが不要になります。
select cube_contains('(0,0),(1,1)', '0.5,0.5');
cube_contains
--------------
t
(1 row)使用例については、sql/cube.sqlリグレッション試験を参照してください。
破壊防止のために立体の次元数に100までという制限を行いました。 これはcubedata.hで設定されており、必要に応じて多少大きくすることができます。
原作者: Gene Selkov, Jr. <selkovjr@mcs.anl.gov>,
Mathematics and Computer Science Division, Argonne National Laboratory.
GiST (http://gist.cs.berkeley.edu/)の要旨（gist）を説明していただいたJoe Hellerstein博士に感謝します。 また、Illustra用の例 http://garcia.me.berkeley.edu/~adong/rtreeの作者である彼の以前の生徒Andy Dong (http://best.me.berkeley.edu/~adong/)に感謝します。 また、自分の世界を作成できるようにし、静かに生活できるようにしてもらった、過去から現在までのすべてのpostgres開発者に感謝します。 データベース研究に長年誠実にサポートしてくれたArgonne LabとU.S. Department of Energyにも感謝します。
2002年8月/9月にBruno Wolff III <bruno@wolff.to>による小規模な改修がこのパッケージになされました。
この改修には、単精度から倍精度への精度の変更といくつかの関数の追加が含まれます。
2006年7月にJoshua Reich <josh@root.net>による改修がさらになされました。
この改修にはcube(float8[], float8[])が含まれ、また、古いV0プロトコルからV1呼び出しプロトコルを使用するようコードが整理されました。