Un valor de celda temporal se introduce utilizando la sintaxis temporal estándar con el identificador de celda de 64 bits subyacente. El analizador de entrada acepta la forma hexadecimal canónica que publica cada cuadrícula — la forma que emiten la CLI de H3 y h3_cell_to_string, y la forma que lee la implementación de referencia de CARTO — con un prefijo 0x opcional, en cualquiera de las dos cajas de letra y con 16 dígitos significativos como máximo. El hexadecimal es idiomático en los tres ecosistemas y es lo que emite la función de salida, de modo que todos los ejemplos siguientes lo usan. El valor debe además denotar algo que su cuadrícula indexe: para H3 una celda, una arista dirigida o un vértice, de modo que un literal hexadecimal bien formado como 12345, que no es ninguno de los tres, se rechaza en lugar de almacenarse como un valor sin ubicación. Como referencia, el hexadecimal 480fffffffffffff usado en los ejemplos es la celda mundial QUADBIN de resolución 0, igual al decimal 5192650370358181887.
Las funciones asBinary y asHexWKB serializan un valor raster o raquet, y rasterFromBinary, rasterFromHexWKB, raquetFromBinary y raquetFromHexWKB lo reconstruyen. Un ráster se escribe en la forma que escribe el ráster de PostGIS, de modo que una columna de rásteres hace un viaje de ida y vuelta entre PostgreSQL y cualquier programa que lea esa forma. Una tesela lleva sus píxeles y su georreferenciación QUADBIN en un único valor, de modo que hace un viaje de ida y vuelta a través de una cadena de bytes portable sin intervención de ninguna extensión espacial, y la forma hexadecimal permite que una columna de teselas haga ese viaje mediante un COPY basado en texto. Ambas funciones de salida aceptan un argumento opcional de ordenación de bytes, NDR para little-endian o XDR para big-endian, cuyo valor predeterminado es la ordenación del servidor.
Entrada y salida de una celda temporal en su forma textual
tcell(text) → tcell text(tcell) → text
El tipo estático acompañante cell contiene un único identificador de celda (no temporal) y cellset un conjunto finito de ellos; comparten la representación textual hexadecimal / decimal del tipo temporal, llevan los operadores estándar de igualdad y de orden a través de una clase de operadores btree y hash, y exponen los predicados de validez de más abajo. Un modificador de tipo restringe una columna a un subtipo, que es Instant, Sequence o SequenceSet.
SELECT th3index '831c02fffffffff@2001-01-01';
-- 831c02fffffffff@2001-01-01
SELECT th3index '[831c02fffffffff@2001-01-01, 831c00fffffffff@2001-01-02]';
-- [831c02fffffffff@2001-01-01, 831c00fffffffff@2001-01-02]
SELECT th3index '{[831c02fffffffff@2001-01-01, 831c00fffffffff@2001-01-02]}';
-- {[831c02fffffffff@2001-01-01, 831c00fffffffff@2001-01-02]}
SELECT tquadbin '48a6227affffffff@2001-01-01';
-- 48a6227affffffff@2001-01-01
SELECT tquadbin '[48a6227affffffff@2001-01-01, 485623ffffffffff@2001-01-02]';
-- [48a6227affffffff@2001-01-01, 485623ffffffffff@2001-01-02]
SELECT tquadbin '{[48a6227affffffff@2001-01-01, 485623ffffffffff@2001-01-02]}';
-- {[48a6227affffffff@2001-01-01, 485623ffffffffff@2001-01-02]}
SELECT ts2cell '47c3c@2001-01-01';
-- 47c3c@2001-01-01
SELECT ts2cell '[47c3c@2001-01-01, 47c4@2001-01-02]';
-- [47c3c@2001-01-01, 47c4@2001-01-02]
SELECT ts2cell '{[47c3c@2001-01-01, 47c4@2001-01-02]}';
-- {[47c3c@2001-01-01, 47c4@2001-01-02]}
Serializar una celda temporal como texto, como binario o como binario bien conocido hexadecimal, con o sin su SRID, o como MF-JSON
asText(tcell) → text asEWKT(tcell) → text asBinary(tcell,endian text='') → bytea asEWKB(tcell,endian text='') → bytea asHexWKB(tcell,endian text='') → text asHexEWKB(tcell,endian text='') → text asMFJSON(tcell) → text
Las formas extendidas asEWKT, asEWKB y asHexEWKB indican el SRID 4326 de una celda, que las demás formas omiten. La forma binaria bien conocida hexadecimal permite que una columna de celdas temporales se transfiera de ida y vuelta mediante un COPY basado en texto. En MF-JSON cada celda del arreglo values es su forma textual en una cadena JSON, el índice hexadecimal de H3 y QUADBIN y el token de S2, ya que un lector JSON que guarda sus números como números de doble precisión pierde los bits bajos de un identificador de celda de 64 bits, y el miembro bbox indica la caja espaciotemporal de las celdas.
SELECT asEWKT(th3index '831c02fffffffff@2001-01-01');
-- SRID=4326;831c02fffffffff@2001-01-01
SELECT asHexEWKB(th3index '831c02fffffffff@2001-01-01');
-- 01460061E6100000FFFFFFFF2FC031080060885EC91C0000
SELECT asHexWKB(th3index '831c02fffffffff@2001-01-01');
-- 01460021FFFFFFFF2FC031080060885EC91C0000
SELECT asHexWKB(tquadbin '48a6227affffffff@2001-01-01');
-- 01490001FFFFFFFF7A22A6480060885EC91C0000
SELECT asHexWKB(ts2cell '47c3c@2001-01-01');
-- 015700210000000000C0C3470060885EC91C0000
SELECT asMFJSON(tquadbin '48a6227affffffff@2001-01-01');
/* {"type":"MovingQuadbin","crs":{"type":"Name","properties":{"name":"EPSG:4326"}},
"values":["48a6227affffffff"],"datetimes":["2001-01-01T00:00:00+00:00"],
"interpolation":"None"} */
Reconstruir una celda temporal a partir de su representación textual, binaria, hexadecimal o MF-JSON
tcellFromText(text) → tcell tcellFromEWKT(text) → tcell tcellFromBinary(bytea) → tcell tcellFromEWKB(bytea) → tcell tcellFromHexWKB(text) → tcell tcellFromHexEWKB(text) → tcell tcellFromMFJSON(text) → tcell
Un SRID indicado por una entrada extendida debe ser 4326, el SRID de una celda. La entrada MF-JSON lee una celda escrita como su forma textual en una cadena JSON y una celda escrita como el número JSON de su identificador de 64 bits.
SELECT ts2cellFromText('47c3c@2001-01-01');
-- 47c3c@2001-01-01
SELECT th3indexFromEWKT('SRID=4326;831c02fffffffff@2001-01-01');
-- 831c02fffffffff@2001-01-01
SELECT tquadbinFromEWKB(asEWKB(tquadbin '48a6227affffffff@2001-01-01'));
-- 48a6227affffffff@2001-01-01
SELECT tquadbinFromMFJSON('{"type":"MovingQuadbin","values":["48a6227affffffff"],
"datetimes":["2001-01-01T00:00:00"],"interpolation":"None"}');
-- 48a6227affffffff@2001-01-01
SELECT tquadbinFromMFJSON('{"type":"MovingQuadbin","values":[5234909528541102079],
"datetimes":["2001-01-01T00:00:00"],"interpolation":"None"}');
-- 48a6227affffffff@2001-01-01
SELECT th3indexFromHexWKB(asHexWKB(th3index '831c02fffffffff@2001-01-01'));
-- 831c02fffffffff@2001-01-01
SELECT tquadbinFromHexWKB(asHexWKB(tquadbin '48a6227affffffff@2001-01-01'));
-- 48a6227affffffff@2001-01-01
SELECT ts2cellFromHexWKB(asHexWKB(ts2cell '47c3c@2001-01-01'));
-- 47c3c@2001-01-01
Devuelve la representación binaria conocida (WKB) o la representación hexadecimal binaria conocida (HexWKB) de una celda
asBinary(cell,endian text='') → bytea asHexWKB(cell,endian text='') → text
Una celda se escribe como su identificador de 64 bits, codificado utilizando la codificación little-endian (NDR) o big-endian (XDR), la codificación de la máquina cuando no se especifica ninguna. El SRID 4326 de una celda, que fija su malla, se omite.
SELECT asBinary(quadbin '48427fffffffffff'); -- \x0100ffffffffff7f4248 SELECT asHexWKB(quadbin '48427fffffffffff', 'XDR'); -- 000048427FFFFFFFFFFF SELECT asHexWKB(s2cell '47c3c444c'); -- 0100000000C044C4C347
Entrada de una celda desde la representación binaria conocida (WKB) o la representación hexadecimal binaria conocida (HexWKB)
cellFromBinary(bytea) → cell cellFromHexWKB(text) → cell
Un SRID indicado por una entrada extendida debe ser 4326, el SRID de una celda, y el identificador debe codificar una celda de la malla.
SELECT quadbinFromHexWKB('0140E6100000FFFFFFFFFF7F4248');
-- 48427fffffffffff
SELECT quadbinFromHexWKB('0140110F0000FFFFFFFFFF7F4248');
-- ERROR: Only SRID 4326 (WGS84) is accepted for the type quadbin, received 3857
Devuelve la representación de texto de una celda
asText(cell) → text
En la función anterior, cell reemplaza h3index, quadbin o s2cell. El texto es el índice hexadecimal de H3 y QUADBIN y el token de S2, la forma que emite la función de salida; para h3index, el tipo de h3-pg, es el texto que escribe la función de salida de h3-pg.
SELECT asText(h3index '831c02fffffffff'); -- 831c02fffffffff SELECT asText(quadbin '48a6227affffffff'); -- 48a6227affffffff SELECT asText(s2cell '47c3c'); -- 47c3c
Entrada desde la representación de texto de una celda
cellFromText(text) → cell
Hay una función por tipo de celda, el nombre de la función tiene como prefijo el nombre del tipo, que es h3index, quadbin o s2cell. La función es la inversa de asText y lee las formas que acepta un literal del tipo, tanto de una constante como de una columna text.
SELECT h3indexFromText('0x831C02FFFFFFFFF');
-- 831c02fffffffff
SELECT quadbinFromText('48a6227affffffff');
-- 48a6227affffffff
SELECT quadbinFromText('0x48a6227affffffff');
-- 48a6227affffffff
SELECT s2cellFromText('47c3c');
-- 47c3c
Devuelve la representación binaria conocida (WKB) de un ráster o de una tesela Raquet
asBinary({raster,raquet},endian text='') → bytea
SELECT length(asBinary(ST_MakeEmptyRaster(2, 2, 0.0, 2.0, 1.0, -1.0, 0.0, 0.0, 4326)));
-- 61
SELECT get_byte(asBinary(ST_MakeEmptyRaster(2, 2, 0.0, 2.0, 1.0, -1.0, 0.0, 0.0, 4326),
'XDR'), 0);
-- 0
SELECT length(asBinary(raquet('\x01020304'::bytea, 2, 2,
quadbin '4817ffffffffffff', 'uint8')));
-- 31
Devuelve la representación hexadecimal binaria conocida (HexWKB) de un ráster o de una tesela Raquet
asHexWKB({raster,raquet},endian text='') → text
SELECT length(asHexWKB(ST_MakeEmptyRaster(2, 2, 0.0, 2.0, 1.0, -1.0, 0.0, 0.0, 4326)));
-- 122
SELECT length(asHexWKB(raquet('\x01020304'::bytea, 2, 2,
quadbin '4817ffffffffffff', 'uint8')));
-- 62
Devuelve un ráster o una tesela Raquet a partir de su representación binaria conocida (WKB)
rasterFromBinary(bytea) → raster raquetFromBinary(bytea) → raquet
SELECT rasterFromBinary(asBinary(r, 'XDR')) = r
FROM (SELECT ST_MakeEmptyRaster(2, 2, 0.0, 2.0, 1.0, -1.0, 0.0, 0.0, 4326) AS r) t;
-- true
SELECT raquetFromBinary(asBinary(raquet('\x01020304'::bytea, 2, 2,
quadbin '4817ffffffffffff', 'uint8')))
= raquet('\x01020304'::bytea, 2, 2, quadbin '4817ffffffffffff', 'uint8');
-- true
Devuelve un ráster o una tesela Raquet a partir de su representación hexadecimal binaria conocida (HexWKB)
rasterFromHexWKB(text) → raster raquetFromHexWKB(text) → raquet
SELECT rasterFromHexWKB(asHexWKB(r, 'XDR')) = r
FROM (SELECT ST_MakeEmptyRaster(2, 2, 0.0, 2.0, 1.0, -1.0, 0.0, 0.0, 4326) AS r) t;
-- true
SELECT raquetFromHexWKB(asHexWKB(raquet('\x01020304'::bytea, 2, 2,
quadbin '4817ffffffffffff', 'uint8')))
= raquet('\x01020304'::bytea, 2, 2, quadbin '4817ffffffffffff', 'uint8');
-- true