src/headers/spatialite/gg_formats.h File Reference

Geometry handling functions: formats. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
GAIAGEO_DECLARE int	gaiaEndianArch (void)
	Test CPU endianness.
GAIAGEO_DECLARE short	gaiaImport16 (const unsigned char *p, int little_endian, int little_endian_arch)
	Import an INT-16 value in endian-aware fashion.
GAIAGEO_DECLARE int	gaiaImport32 (const unsigned char *p, int little_endian, int little_endian_arch)
	Import an INT-32 value in endian-aware fashion.
GAIAGEO_DECLARE float	gaiaImportF32 (const unsigned char *p, int little_endian, int little_endian_arch)
	Import a FLOAT-32 value in endian-aware fashion.
GAIAGEO_DECLARE double	gaiaImport64 (const unsigned char *p, int little_endian, int little_endian_arch)
	Import an DOUBLE-64 in endian-aware fashion.
GAIAGEO_DECLARE sqlite3_int64	gaiaImportI64 (const unsigned char *p, int little_endian, int little_endian_arch)
	Import an INT-64 in endian-aware fashion.
GAIAGEO_DECLARE void	gaiaExport16 (unsigned char *p, short value, int little_endian, int little_endian_arch)
	Export an INT-16 value in endian-aware fashion.
GAIAGEO_DECLARE void	gaiaExport32 (unsigned char *p, int value, int little_endian, int little_endian_arch)
	Export an INT-32 value in endian-aware fashion.
GAIAGEO_DECLARE void	gaiaExportF32 (unsigned char *p, float value, int little_endian, int little_endian_arch)
	Export a FLOAT-32 value in endian-aware fashion.
GAIAGEO_DECLARE void	gaiaExport64 (unsigned char *p, double value, int little_endian, int little_endian_arch)
	Export a DOUBLE value in endian-aware fashion.
GAIAGEO_DECLARE void	gaiaExportI64 (unsigned char *p, sqlite3_int64 value, int little_endian, int little_endian_arch)
	Export an INT-64 value in endian-aware fashion.
GAIAGEO_DECLARE void	gaiaOutBufferInitialize (gaiaOutBufferPtr buf)
	Initializes a dynamically growing Text output buffer.
GAIAGEO_DECLARE void	gaiaOutBufferReset (gaiaOutBufferPtr buf)
	Resets a dynamically growing Text output buffer to its initial (empty) state.
GAIAGEO_DECLARE void	gaiaAppendToOutBuffer (gaiaOutBufferPtr buf, const char *text)
	Appends a text string at the end of Text output buffer.
GAIAGEO_DECLARE void	gaiaMakePoint (double x, double y, int srid, unsigned char **result, int *size)
	Creates a BLOB-Geometry representing a Point.
GAIAGEO_DECLARE void	gaiaMakeLine (gaiaGeomCollPtr geom1, gaiaGeomCollPtr geom2, unsigned char **result, int *size)
	Creates a BLOB-Geometry representing a Segment (2-Points Linestring)
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaFromSpatiaLiteBlobWkb (const unsigned char *blob, unsigned int size)
	Creates a Geometry object from the corresponding BLOB-Geometry.
GAIAGEO_DECLARE void	gaiaToSpatiaLiteBlobWkb (gaiaGeomCollPtr geom, unsigned char **result, int *size)
	Creates a BLOB-Geometry corresponding to a Geometry object.
GAIAGEO_DECLARE void	gaiaToCompressedBlobWkb (gaiaGeomCollPtr geom, unsigned char **result, int *size)
	Creates a Compressed BLOB-Geometry corresponding to a Geometry object.
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaFromWkb (const unsigned char *blob, unsigned int size)
	Creates a Geometry object from WKB notation.
GAIAGEO_DECLARE void	gaiaToWkb (gaiaGeomCollPtr geom, unsigned char **result, int *size)
	Encodes a Geometry object into WKB notation.
GAIAGEO_DECLARE char *	gaiaToHexWkb (gaiaGeomCollPtr geom)
	Encodes a Geometry object into (hex) WKB notation.
GAIAGEO_DECLARE void	gaiaToEWKB (gaiaOutBufferPtr out_buf, gaiaGeomCollPtr geom)
	Encodes a Geometry object into EWKB notation.
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaFromEWKB (const unsigned char *in_buffer)
	Creates a Geometry object from EWKB notation.
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaFromFgf (const unsigned char *blob, unsigned int size)
	Creates a Geometry object from FGF notation.
GAIAGEO_DECLARE void	gaiaToFgf (gaiaGeomCollPtr geom, unsigned char **result, int *size, int coord_dims)
	Encodes a Geometry object into FGF notation.
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaParseWkt (const unsigned char *in_buffer, short type)
	Creates a Geometry object from WKT notation.
GAIAGEO_DECLARE void	gaiaOutWkt (gaiaOutBufferPtr out_buf, gaiaGeomCollPtr geom)
	Encodes a Geometry object into WKT notation.
GAIAGEO_DECLARE void	gaiaOutWktStrict (gaiaOutBufferPtr out_buf, gaiaGeomCollPtr geom, int precision)
	Encodes a Geometry object into strict 2D WKT notation.
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaParseEWKT (const unsigned char *in_buffer)
	Creates a Geometry object from EWKT notation.
GAIAGEO_DECLARE void	gaiaToEWKT (gaiaOutBufferPtr out_buf, gaiaGeomCollPtr geom)
	Encodes a Geometry object into EWKT notation.
GAIAGEO_DECLARE void	gaiaOutPointZ (gaiaOutBufferPtr out_buf, gaiaPointPtr point)
	Encodes a WKT 3D Point [XYZ].
GAIAGEO_DECLARE void	gaiaOutLinestringZ (gaiaOutBufferPtr out_buf, gaiaLinestringPtr linestring)
	Encodes a WKT 3D Linestring [XYZ].
GAIAGEO_DECLARE void	gaiaOutPolygonZ (gaiaOutBufferPtr out_buf, gaiaPolygonPtr polygon)
	Encodes a WKT 3D Polygon [XYZ].
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaParseKml (const unsigned char *in_buffer)
	Creates a Geometry object from KML notation.
GAIAGEO_DECLARE void	gaiaOutBareKml (gaiaOutBufferPtr out_buf, gaiaGeomCollPtr geom, int precision)
	Encodes a Geometry object into KML notation.
GAIAGEO_DECLARE void	gaiaOutFullKml (gaiaOutBufferPtr out_buf, const char *name, const char *desc, gaiaGeomCollPtr geom, int precision)
	Encodes a Geometry object into KML notation.
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaParseGml (const unsigned char *in_buffer, sqlite3 *sqlite_handle)
	Creates a Geometry object from GML notation.
GAIAGEO_DECLARE void	gaiaOutGml (gaiaOutBufferPtr out_buf, int version, int precision, gaiaGeomCollPtr geom)
	Encodes a Geometry object into GML notation.
GAIAGEO_DECLARE gaiaGeomCollPtr	gaiaParseGeoJSON (const unsigned char *in_buffer)
	Creates a Geometry object from GeoJSON notation.
GAIAGEO_DECLARE void	gaiaOutGeoJSON (gaiaOutBufferPtr out_buf, gaiaGeomCollPtr geom, int precision, int options)
	Encodes a Geometry object into GeoJSON notation.
GAIAGEO_DECLARE void	gaiaOutSvg (gaiaOutBufferPtr out_buf, gaiaGeomCollPtr geom, int relative, int precision)
	Encodes a Geometry object into SVG notation.
GAIAGEO_DECLARE gaiaValuePtr	gaiaCloneValue (gaiaValuePtr org)
	Allocates a new DBF Field Value object [duplicating an existing one].
GAIAGEO_DECLARE void	gaiaFreeValue (gaiaValuePtr p)
	Resets a DBF Field Value object to its initial empty state.
GAIAGEO_DECLARE gaiaDbfFieldPtr	gaiaAllocDbfField (char *name, unsigned char type, int offset, unsigned char length, unsigned char decimals)
	Allocates a new DBF Field object.
GAIAGEO_DECLARE void	gaiaFreeDbfField (gaiaDbfFieldPtr p)
	Destroys a DBF Field object.
GAIAGEO_DECLARE gaiaDbfFieldPtr	gaiaCloneDbfField (gaiaDbfFieldPtr org)
	Allocates a new DBF Field object [duplicating an existing one].
GAIAGEO_DECLARE void	gaiaSetNullValue (gaiaDbfFieldPtr field)
	Sets a NULL current value for a DBF Field object.
GAIAGEO_DECLARE void	gaiaSetIntValue (gaiaDbfFieldPtr field, sqlite3_int64 value)
	Sets an INTEGER current value for a DBF Field object.
GAIAGEO_DECLARE void	gaiaSetDoubleValue (gaiaDbfFieldPtr field, double value)
	Sets a DOUBLE current value for a DBF Field object.
GAIAGEO_DECLARE void	gaiaSetStrValue (gaiaDbfFieldPtr field, char *str)
	Sets a TEXT current value for a DBF Field object.
GAIAGEO_DECLARE gaiaDbfListPtr	gaiaAllocDbfList (void)
	Creates an initially empty DBF List object.
GAIAGEO_DECLARE void	gaiaFreeDbfList (gaiaDbfListPtr list)
	Destroys a DBF List object.
GAIAGEO_DECLARE int	gaiaIsValidDbfList (gaiaDbfListPtr list)
	Checks a DBF List object for validity.
GAIAGEO_DECLARE gaiaDbfFieldPtr	gaiaAddDbfField (gaiaDbfListPtr list, char *name, unsigned char type, int offset, unsigned char length, unsigned char decimals)
	Inserts a further DBF Field object into a DBF List object.
GAIAGEO_DECLARE void	gaiaResetDbfEntity (gaiaDbfListPtr list)
	Resets a DBF List object to its initial empty state.
GAIAGEO_DECLARE gaiaDbfListPtr	gaiaCloneDbfEntity (gaiaDbfListPtr org)
	Allocates a new DBF List object [duplicating an existing one].
GAIAGEO_DECLARE gaiaShapefilePtr	gaiaAllocShapefile (void)
	Allocates a new Shapefile object.
GAIAGEO_DECLARE void	gaiaFreeShapefile (gaiaShapefilePtr shp)
	Destroys a Shapefile object.
GAIAGEO_DECLARE void	gaiaOpenShpRead (gaiaShapefilePtr shp, const char *path, const char *charFrom, const char *charTo)
	Open a Shapefile in read mode.
GAIAGEO_DECLARE void	gaiaOpenShpWrite (gaiaShapefilePtr shp, const char *path, int shape, gaiaDbfListPtr list, const char *charFrom, const char *charTo)
	Open a Shapefile in read mode.
GAIAGEO_DECLARE int	gaiaReadShpEntity (gaiaShapefilePtr shp, int current_row, int srid)
	Reads a feature from a Shapefile object.
GAIAGEO_DECLARE void	gaiaShpAnalyze (gaiaShapefilePtr shp)
	Prescans a Shapefile object gathering informations.
GAIAGEO_DECLARE int	gaiaWriteShpEntity (gaiaShapefilePtr shp, gaiaDbfListPtr entity)
	Writes a feature into a Shapefile object.
GAIAGEO_DECLARE void	gaiaFlushShpHeaders (gaiaShapefilePtr shp)
	Writes into an output Shapefile any required header / footer.
GAIAGEO_DECLARE gaiaDbfPtr	gaiaAllocDbf (void)
	Allocates a new DBF File object.
GAIAGEO_DECLARE void	gaiaFreeDbf (gaiaDbfPtr dbf)
	Destroys a DBF File object.
GAIAGEO_DECLARE void	gaiaOpenDbfRead (gaiaDbfPtr dbf, const char *path, const char *charFrom, const char *charTo)
	Open a DBF File in read mode.
GAIAGEO_DECLARE void	gaiaOpenDbfWrite (gaiaDbfPtr dbf, const char *path, const char *charFrom, const char *charTo)
	Open a DBF File in write mode.
GAIAGEO_DECLARE int	gaiaReadDbfEntity (gaiaDbfPtr dbf, int current_row, int *deleted)
	Reads a record from a DBF File object.
GAIAGEO_DECLARE int	gaiaWriteDbfEntity (gaiaDbfPtr dbf, gaiaDbfListPtr entity)
	Writes a record into a DBF File object.
GAIAGEO_DECLARE void	gaiaFlushDbfHeader (gaiaDbfPtr dbf)
	Writes into an output DBF File any required header / footer.
GAIAGEO_DECLARE gaiaTextReaderPtr	gaiaTextReaderAlloc (const char *path, char field_separator, char text_separator, char decimal_separator, int first_line_titles, const char *encoding)
	Creates a Text Reader object.
GAIAGEO_DECLARE void	gaiaTextReaderDestroy (gaiaTextReaderPtr reader)
	Destroys a Text Reader object.
GAIAGEO_DECLARE int	gaiaTextReaderParse (gaiaTextReaderPtr reader)
	Prescans the external file associated to a Text Reade object.
GAIAGEO_DECLARE int	gaiaTextReaderGetRow (gaiaTextReaderPtr reader, int row_num)
	Reads a line from a Text Reader object.
GAIAGEO_DECLARE int	gaiaTextReaderFetchField (gaiaTextReaderPtr reader, int field_num, int *type, const char **value)
	Retrieves an individual field value from the current Line.

---

Detailed Description

Geometry handling functions: formats.

---

Function Documentation

GAIAGEO_DECLARE gaiaDbfFieldPtr gaiaAddDbfField	(	gaiaDbfListPtr	list,
		char *	name,
		unsigned char	type,
		int	offset,
		unsigned char	length,
		unsigned char	decimals
	)

Inserts a further DBF Field object into a DBF List object.

Parameters:

list	pointer to the DBF List object.
name	text string: DBF Field name.
type	identifier of the corresponding DBF data type.
offset	corresponding offset into the DBF I/O buffer.
length	max field length (in bytes).
decimals	precision: number of decimal digits.

Returns:

the pointer to newly created DBF Field object.

See also:

gaiaAllocDbfField

Note:

supported DBF data types are:

• 'C' text string [default]
• 'N' numeric
• 'D' date
• 'L' boolean

GAIAGEO_DECLARE gaiaDbfPtr gaiaAllocDbf

(

void

)

Allocates a new DBF File object.

Returns:

the pointer to newly created DBF File object.

See also:

gaiaFreeDbf, gaiaOpenDbfRead, gaiaOpenDbfWrite, gaiaReadDbfEntity, gaiaWriteDbfEntity, gaiaFlushDbfHeader

Note:

you are responsible to destroy (before or after) any allocated DBF File.
you should phisically open the DBF File in read or write mode before performing any actual I/O operation.

GAIAGEO_DECLARE gaiaDbfFieldPtr gaiaAllocDbfField	(	char *	name,
		unsigned char	type,
		int	offset,
		unsigned char	length,
		unsigned char	decimals
	)

Allocates a new DBF Field object.

Parameters:

name	text string: DBF Field name.
type	identifier of the corresponding DBF data type.
offset	corresponding offset into the DBF I/O buffer.
length	max field length (in bytes).
decimals	precision: number of decimal digits.

Returns:

the pointer to newly created DBF Field object.

See also:

gaiaFreeDbfField, gaiaCloneDbfField, gaiaFreeValue, gaiaSetNullValue, gaiaSetIntValue, gaiaSetDoubleValue, gaiaSetStrValue

Note:

you are responsible to destroy (before or after) any allocated DBF Field, unless you've passed ownership to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.
supported DBF data types are:

• 'C' text string [default]
• 'N' numeric
• 'D' date
• 'L' boolean

GAIAGEO_DECLARE gaiaDbfListPtr gaiaAllocDbfList

(

void

)

Creates an initially empty DBF List object.

Returns:

the pointer to newly allocated DBF List object: NULL on failure.

See also:

gaiaFreeDbfList, gaiaIsValidDbfList, gaiaResetDbfEntity, gaiaCloneDbfEntity, gaiaAddDbfField

Note:

you are responsible to destroy (before or after) any allocated DBF List, unless you've passed ownership to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaShapefilePtr gaiaAllocShapefile

(

void

)

Allocates a new Shapefile object.

Returns:

the pointer to newly created Shapefile object.

See also:

gaiaFreeShapefile, gaiaOpenShpRead, gaiaOpenShpWrite, gaiaReadShpEntity, gaiaShpAnalyze, gaiaWriteShpEntity, gaiaFlushShpHeaders

Note:

you are responsible to destroy (before or after) any allocated Shapefile.
you should phisically open the Shapefile in read or write mode before performing any actual I/O operation.

GAIAGEO_DECLARE void gaiaAppendToOutBuffer	(	gaiaOutBufferPtr	buf,
		const char *	text
	)

Appends a text string at the end of Text output buffer.

Parameters:

buf	pointer to gaiaOutBufferStruct structure.
text	the text string to be appended.

See also:

gaiaOutBufferInitialize, gaiaOutBufferReset

Note:

You are required to initialize this structure before attempting any further operation: the dynamically growing Text buffer will be automatically allocated and/or extended as required.

GAIAGEO_DECLARE gaiaDbfListPtr gaiaCloneDbfEntity

(

gaiaDbfListPtr

org

)

Allocates a new DBF List object [duplicating an existing one].

Parameters:

org	pointer to input DBF List object.

Returns:

the pointer to newly created DBF List object.

See also:

gaiaCloneDbfField, gaiaCloneValue,

Note:

the newly created object is an exact copy of the original one.
this including any currently set Field Value.

GAIAGEO_DECLARE gaiaDbfFieldPtr gaiaCloneDbfField

(

gaiaDbfFieldPtr

org

)

Allocates a new DBF Field object [duplicating an existing one].

Parameters:

org	pointer to input DBF Field object.

Returns:

the pointer to newly created DBF Field object.

See also:

gaiaAllocDbfField, gaiaFreeDbfField, gaiaCloneDbfField, gaiaFreeValue, gaiaSetNullValue, gaiaSetIntValue, gaiaSetDoubleValue, gaiaSetStrValue

Note:

the newly created object is an exact copy of the original one [this including an evantual Field Value].

GAIAGEO_DECLARE gaiaValuePtr gaiaCloneValue

(

gaiaValuePtr

org

)

Allocates a new DBF Field Value object [duplicating an existing one].

Parameters:

org	pointer to input DBF Field Value object.

Returns:

the pointer to newly created DBF Field object.

See also:

gaiaAllocDbfField, gaiaFreeDbfField, gaiaCloneDbfField, gaiaCloneValue, gaiaSetNullValue, gaiaSetIntValue, gaiaSetDoubleValue, gaiaSetStrValue

Note:

the newly created object is an exact copy of the original one.

GAIAGEO_DECLARE int gaiaEndianArch

(

void

)

Test CPU endianness.

Returns:

0 if big-endian: any other value if little-endian

GAIAGEO_DECLARE void gaiaExport16	(	unsigned char *	p,
		short	value,
		int	little_endian,
		int	little_endian_arch
	)

Export an INT-16 value in endian-aware fashion.

Parameters:

p	endian-dependent representation (output buffer).
value	the internal value to be exported.
little_endian	0 if the output buffer has to be big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

See also:

gaiaEndianArch, gaiaImport16

Note:

you are expected to pass an output buffer corresponding to an allocation size of (at least) 2 bytes.

GAIAGEO_DECLARE void gaiaExport32	(	unsigned char *	p,
		int	value,
		int	little_endian,
		int	little_endian_arch
	)

Export an INT-32 value in endian-aware fashion.

Parameters:

p	endian-dependent representation (output buffer).
value	the internal value to be exported.
little_endian	0 if the output buffer has to be big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

See also:

gaiaEndianArch, gaiaImport32

Note:

you are expected to pass an output buffer corresponding to an allocation size of (at least) 4 bytes.

GAIAGEO_DECLARE void gaiaExport64	(	unsigned char *	p,
		double	value,
		int	little_endian,
		int	little_endian_arch
	)

Export a DOUBLE value in endian-aware fashion.

Parameters:

p	endian-dependent representation (output buffer).
value	the internal value to be exported.
little_endian	0 if the output buffer has to be big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

See also:

gaiaEndianArch, gaiaImport64

Note:

you are expected to pass an output buffer corresponding to an allocation size of (at least) 8 bytes.

GAIAGEO_DECLARE void gaiaExportF32	(	unsigned char *	p,
		float	value,
		int	little_endian,
		int	little_endian_arch
	)

Export a FLOAT-32 value in endian-aware fashion.

Parameters:

p	endian-dependent representation (output buffer).
value	the internal value to be exported.
little_endian	0 if the output buffer has to be big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

See also:

gaiaEndianArch, gaiaImportF32

Note:

you are expected to pass an output buffer corresponding to an allocation size of (at least) 4 bytes.

GAIAGEO_DECLARE void gaiaExportI64	(	unsigned char *	p,
		sqlite3_int64	value,
		int	little_endian,
		int	little_endian_arch
	)

Export an INT-64 value in endian-aware fashion.

Parameters:

p	endian-dependent representation (output buffer).
value	the internal value to be exported.
little_endian	0 if the output buffer has to be big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

See also:

gaiaEndianArch, gaiaImportI64

Note:

you are expected to pass an output buffer corresponding to an allocation size of (at least) 8 bytes.

GAIAGEO_DECLARE void gaiaFlushDbfHeader

(

gaiaDbfPtr

dbf

)

Writes into an output DBF File any required header / footer.

Parameters:

dbf	pointer to the DBF File object.

See also:

gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfRead, gaiaOpenDbfWrite, gaiaReadDbfEntity, gaiaWriteDbfEntity

Note:

forgetting to call gaiaFlushDbfHeader for any DBF File opened in write mode immediately before destroying the object, will surely cause severe file corruption.

GAIAGEO_DECLARE void gaiaFlushShpHeaders

(

gaiaShapefilePtr

shp

)

Writes into an output Shapefile any required header / footer.

Parameters:

shp	pointer to the Shapefile object.

See also:

gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpRead, gaiaOpenShpWrite, gaiaReadShpEntity, gaiaShpAnalyze, gaiaWriteShpEntity

Note:

forgetting to call gaiaFlushShpHeader for any Shapefile opened in write mode immediately before destroying the object, will surely cause severe file corruption.

GAIAGEO_DECLARE void gaiaFreeDbf

(

gaiaDbfPtr

dbf

)

Destroys a DBF File object.

Parameters:

dbf	pointer to the DBF File object.

See also:

gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfWrite, gaiaReadDbfEntity, gaiaWriteDbfEntity, gaiaFlushDbfHeader

Note:

destroying the Shapefile object will close any related file: anyway you a responsible to explicitly call gaiaFlushShpHeader before destroyng a Shapefile opened in write mode.

GAIAGEO_DECLARE void gaiaFreeDbfField

(

gaiaDbfFieldPtr

p

)

Destroys a DBF Field object.

Parameters:

p	pointer to DBF Field object

See also:

gaiaAllocDbfField, gaiaCloneDbfField, gaiaCloneValue, gaiaFreeValue, gaiaSetNullValue, gaiaSetIntValue, gaiaSetDoubleValue, gaiaSetStrValue

GAIAGEO_DECLARE void gaiaFreeDbfList

(

gaiaDbfListPtr

list

)

Destroys a DBF List object.

Parameters:

list	pointer to the DBF List object

See also:

gaiaAllocDbfList, gaiaIsValidDbfList, gaiaResetDbfEntity, gaiaCloneDbfEntity, gaiaAddDbfField

Note:

attempting to destroy any DBF List object whose ownnership has already been transferred to some other (higher order) object is a serious error, and will easily cause severe memory corruption.

GAIAGEO_DECLARE void gaiaFreeShapefile

(

gaiaShapefilePtr

shp

)

Destroys a Shapefile object.

Parameters:

shp	pointer to the Shapefile object.

See also:

gaiaAllocShapefile, gaiaOpenShpRead, gaiaOpenShpWrite, gaiaReadShpEntity, gaiaShpAnalyze, gaiaWriteShpEntity, gaiaFlushShpHeaders

Note:

destroying the Shapefile object will close any related file: anyway you a responsible to explicitly call gaiaFlushShpHeader before destroyng a Shapefile opened in write mode.

GAIAGEO_DECLARE void gaiaFreeValue

(

gaiaValuePtr

p

)

Resets a DBF Field Value object to its initial empty state.

Parameters:

p	pointer to DBF Field Value object

See also:

gaiaAllocDbfField, gaiaCloneDbfField, gaiaCloneValue, gaiaSetNullValue, gaiaSetIntValue, gaiaSetDoubleValue, gaiaSetStrValue, gaiaResetDbfEntity

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaFromEWKB

(

const unsigned char *

in_buffer

)

Creates a Geometry object from EWKB notation.

Parameters:

in_buffer

pointer to EWKB buffer

Returns:

the pointer to the newly created Geometry object: NULL on failure.

See also:

gaiaToWkb, gaiaToHexWkb, gaiaFromEWKB, gaiaToEWKB

Note:

you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaFromFgf	(	const unsigned char *	blob,
		unsigned int	size
	)

Creates a Geometry object from FGF notation.

Parameters:

blob	pointer to FGF buffer
size	the BLOB's size (in bytes)

Returns:

the pointer to the newly created Geometry object: NULL on failure.

See also:

gaiaToFgf

Note:

you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaFromSpatiaLiteBlobWkb	(	const unsigned char *	blob,
		unsigned int	size
	)

Creates a Geometry object from the corresponding BLOB-Geometry.

Parameters:

blob	pointer to BLOB-Geometry
size	the BLOB's size

Returns:

the pointer to the newly created Geometry object: NULL on failure

See also:

gaiaFreeGeomColl, gaiaToSpatiaLiteBlobWkb, gaiaToCompressedBlobWkb

Note:

you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

Examples:

demo1.c.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaFromWkb	(	const unsigned char *	blob,
		unsigned int	size
	)

Creates a Geometry object from WKB notation.

Parameters:

blob	pointer to WKB buffer
size	the BLOB's size (in bytes)

Returns:

the pointer to the newly created Geometry object: NULL on failure.

See also:

gaiaToWkb, gaiaToHexWkb, gaiaFromEWKB, gaiaToEWKB

Note:

you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE short gaiaImport16	(	const unsigned char *	p,
		int	little_endian,
		int	little_endian_arch
	)

Import an INT-16 value in endian-aware fashion.

Parameters:

p	endian-dependent representation (input buffer).
little_endian	0 if the input buffer is big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

Returns:

the internal SHORT value

See also:

gaiaEndianArch, gaiaExport16

Note:

you are expected to pass an input buffer corresponding to an allocation size of (at least) 2 bytes.

GAIAGEO_DECLARE int gaiaImport32	(	const unsigned char *	p,
		int	little_endian,
		int	little_endian_arch
	)

Import an INT-32 value in endian-aware fashion.

Parameters:

p	endian-dependent representation (input buffer).
little_endian	0 if the input buffer is big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

Returns:

the internal INT value

See also:

gaiaEndianArch, gaiaExport32

Note:

you are expected to pass an input buffer corresponding to an allocation size of (at least) 4 bytes.

GAIAGEO_DECLARE double gaiaImport64	(	const unsigned char *	p,
		int	little_endian,
		int	little_endian_arch
	)

Import an DOUBLE-64 in endian-aware fashion.

Parameters:

p	endian-dependent representation (input buffer).
little_endian	0 if the input buffer is big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

Returns:

the internal DOUBLE value

See also:

gaiaEndianArch, gaiaExport64

Note:

you are expected to pass an input buffer corresponding to an allocation size of (at least) 8 bytes.

GAIAGEO_DECLARE float gaiaImportF32	(	const unsigned char *	p,
		int	little_endian,
		int	little_endian_arch
	)

Import a FLOAT-32 value in endian-aware fashion.

Parameters:

p	endian-dependent representation (input buffer).
little_endian	0 if the input buffer is big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

Returns:

the internal FLOAT value

See also:

gaiaEndianArch, gaiaExportF32

Note:

you are expected to pass an input buffer corresponding to an allocation size of (at least) 4 bytes.

GAIAGEO_DECLARE sqlite3_int64 gaiaImportI64	(	const unsigned char *	p,
		int	little_endian,
		int	little_endian_arch
	)

Import an INT-64 in endian-aware fashion.

Parameters:

p	endian-dependent representation (input buffer).
little_endian	0 if the input buffer is big-endian: any other value for little-endian.
little_endian_arch	the value returned by gaiaEndianArch()

Returns:

the internal INT-64 value

See also:

gaiaEndianArch, gaiaExportI64

Note:

you are expected to pass an input buffer corresponding to an allocation size of (at least) 8 bytes.

GAIAGEO_DECLARE int gaiaIsValidDbfList

(

gaiaDbfListPtr

list

)

Checks a DBF List object for validity.

Parameters:

list	pointer to the DBF List object.

Returns:

0 if not valid: any other value if valid.

See also:

gaiaAllocDbfList, gaiaFreeDbfList, gaiaIsValidDbfList, gaiaResetDbfEntity, gaiaCloneDbfEntity, gaiaAddDbfField

GAIAGEO_DECLARE void gaiaMakeLine	(	gaiaGeomCollPtr	geom1,
		gaiaGeomCollPtr	geom2,
		unsigned char **	result,
		int *	size
	)

Creates a BLOB-Geometry representing a Segment (2-Points Linestring)

Parameters:

geom1	pointer to first Geometry object (expected to represent a Point).
geom2	pointer to second Geometry object (expected to represent a Point).
result	on completion will containt a pointer to BLOB-Geometry: NULL on failure.
size	on completion this variable will contain the BLOB's size (in bytes)

See also:

gaiaFromSpatiaLiteBlobWkb

Note:

the BLOB buffer corresponds to dynamically allocated memory: so you are responsible to free() it [unless SQLite will take care of memory cleanup via buffer binding].

GAIAGEO_DECLARE void gaiaMakePoint	(	double	x,
		double	y,
		int	srid,
		unsigned char **	result,
		int *	size
	)

Creates a BLOB-Geometry representing a Point.

Parameters:

x	Point X coordinate.
y	Point Y coordinate.
srid	the SRID to be set for the Point.
result	on completion will containt a pointer to BLOB-Geometry: NULL on failure.
size	on completion this variable will contain the BLOB's size (in bytes)

See also:

gaiaFromSpatiaLiteBlobWkb

Note:

the BLOB buffer corresponds to dynamically allocated memory: so you are responsible to free() it [unless SQLite will take care of memory cleanup via buffer binding].

GAIAGEO_DECLARE void gaiaOpenDbfRead	(	gaiaDbfPtr	dbf,
		const char *	path,
		const char *	charFrom,
		const char *	charTo
	)

Open a DBF File in read mode.

Parameters:

dbf	pointer to the DBF File object.
path	pathname to the corresponding file-system file.
charFrom	GNU ICONV name identifying the input charset encoding.
charTo	GNU ICONV name identifying the output charset encoding.

See also:

gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfWrite, gaiaReadDbfEntity, gaiaWriteDbfEntity, gaiaFlushDbfHeader

Note:

on failure the object member Valid will be set to 0; and the object member LastError will contain the appropriate error message.

GAIAGEO_DECLARE void gaiaOpenDbfWrite	(	gaiaDbfPtr	dbf,
		const char *	path,
		const char *	charFrom,
		const char *	charTo
	)

Open a DBF File in write mode.

Parameters:

dbf	pointer to the DBF File object.
path	pathname to the corresponding file-system file.
charFrom	GNU ICONV name identifying the input charset encoding.
charTo	GNU ICONV name identifying the output charset encoding.

See also:

gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfRead, gaiaReadDbfEntity, gaiaWriteDbfEntity, gaiaFlushDbfHeader

Note:

on failure the object member Valid will be set to 0; and the object member LastError will contain the appropriate error message.

GAIAGEO_DECLARE void gaiaOpenShpRead	(	gaiaShapefilePtr	shp,
		const char *	path,
		const char *	charFrom,
		const char *	charTo
	)

Open a Shapefile in read mode.

Parameters:

shp	pointer to the Shapefile object.
path	abstract pathname to the corresponding file-system files.
charFrom	GNU ICONV name identifying the input charset encoding.
charTo	GNU ICONV name identifying the output charset encoding.

See also:

gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpWrite, gaiaReadShpEntity, gaiaShpAnalyze, gaiaWriteShpEntity, gaiaFlushShpHeaders

Note:

on failure the object member Valid will be set to 0; and the object member LastError will contain the appropriate error message.
the abstract pathname should not contain any suffix at all.

GAIAGEO_DECLARE void gaiaOpenShpWrite	(	gaiaShapefilePtr	shp,
		const char *	path,
		int	shape,
		gaiaDbfListPtr	list,
		const char *	charFrom,
		const char *	charTo
	)

Open a Shapefile in read mode.

Parameters:

shp	pointer to the Shapefile object.
path	abstract pathname to the corresponding file-system files.
shape	the SHAPE code; expected to be one of GAIA_SHP_POINT, GAIA_SHP_POLYLINE, GAIA_SHP_POLYGON, GAIA_SHP_MULTIPOINT, GAIA_SHP_POINTZ, GAIA_SHP_POLYLINEZ, GAIA_SHP_POLYGONZ, GAIA_SHP_MULTIPOINTZ, GAIA_SHP_POINTM, GAIA_SHP_POLYLINEM, GAIA_SHP_POLYGONM, GAIA_SHP_MULTIPOINTM
list	pointer to DBF List object representing the corresponding data attributes.
charFrom	GNU ICONV name identifying the input charset encoding.
charTo	GNU ICONV name identifying the output charset encoding.

See also:

gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpRead, gaiaReadShpEntity, gaiaShpAnalyze, gaiaWriteShpEntity, gaiaFlushShpHeaders

Note:

on failure the object member Valid will be set to 0; and the object member LastError will contain the appropriate error message.
the abstract pathname should not contain any suffix at all.

GAIAGEO_DECLARE void gaiaOutBareKml	(	gaiaOutBufferPtr	out_buf,
		gaiaGeomCollPtr	geom,
		int	precision
	)

Encodes a Geometry object into KML notation.

Parameters:

out_buf	pointer to dynamically growing Text buffer
geom	pointer to Geometry object
precision	decimal digits to be used for coordinates

See also:

gaiaParseKml, gaiaOutFullKml

Note:

this function will export the simplest KML notation (no descriptions).

GAIAGEO_DECLARE void gaiaOutBufferInitialize

(

gaiaOutBufferPtr

buf

)

Initializes a dynamically growing Text output buffer.

Parameters:

buf	pointer to gaiaOutBufferStruct structure

See also:

gaiaOutBufferReset, gaiaAppendToOutBuffer

Note:

Text notations representing Geometry objects may easily require a huge storage amount: the gaiaOutBufferStruct automatically supports a dynamically growing output buffer.
You are required to initialize this structure before attempting any further operation; and you are responsible to cleanup any related memory allocation when it's any longer required.

Examples:

demo2.c.

GAIAGEO_DECLARE void gaiaOutBufferReset

(

gaiaOutBufferPtr

buf

)

Resets a dynamically growing Text output buffer to its initial (empty) state.

Parameters:

buf	pointer to gaiaOutBufferStruct structure

See also:

gaiaOutBufferInitialize, gaiaAppendToOutBuffer

Note:

You are required to initialize this structure before attempting any further operation: this function will release any related memory allocation.

Examples:

demo2.c.

GAIAGEO_DECLARE void gaiaOutFullKml	(	gaiaOutBufferPtr	out_buf,
		const char *	name,
		const char *	desc,
		gaiaGeomCollPtr	geom,
		int	precision
	)

Encodes a Geometry object into KML notation.

Parameters:

out_buf	pointer to dynamically growing Text buffer
name	text string to be set as KML name
desc	text string to se set as KML description
geom	pointer to Geometry object
precision	decimal digits to be used for coordinates

See also:

gaiaParseKml, gaiaOutBareKml

Note:

this function will export the simplest KML notation (no descriptions).

GAIAGEO_DECLARE void gaiaOutGeoJSON	(	gaiaOutBufferPtr	out_buf,
		gaiaGeomCollPtr	geom,
		int	precision,
		int	options
	)

Encodes a Geometry object into GeoJSON notation.

Parameters:

out_buf	pointer to dynamically growing Text buffer
geom	pointer to Geometry object
precision	decimal digits to be used for coordinates
options	GeoJSON specific options

See also:

gaiaParseGeoJSON

Note:

options can assume the following values:

• 1 = BBOX, no CRS
• 2 = no BBOX, short form CRS
• 3 = BBOX, short form CRS
• 4 = no BBOX, long form CRS
• 5 = BBOX, long form CRS
• any other value: no BBOX and no CRS

GAIAGEO_DECLARE void gaiaOutGml	(	gaiaOutBufferPtr	out_buf,
		int	version,
		int	precision,
		gaiaGeomCollPtr	geom
	)

Encodes a Geometry object into GML notation.

Parameters:

out_buf	pointer to dynamically growing Text buffer
version	GML version
precision	decimal digits to be used for coordinates
geom	pointer to Geometry object

See also:

gaiaParseGml

Note:

if version is set to 3, then GMLv3 will be used; in any other case GMLv2 will be assumed by default.

GAIAGEO_DECLARE void gaiaOutLinestringZ	(	gaiaOutBufferPtr	out_buf,
		gaiaLinestringPtr	linestring
	)

Encodes a WKT 3D Linestring [XYZ].

Parameters:

out_buf	pointer to dynamically growing Text buffer
linestring	pointer to Linestring object

See also:

gaiaOutPointZ, gaiaOutPolygonZ

Remarks:

mainly intended for internal usage.

GAIAGEO_DECLARE void gaiaOutPointZ	(	gaiaOutBufferPtr	out_buf,
		gaiaPointPtr	point
	)

Encodes a WKT 3D Point [XYZ].

Parameters:

out_buf	pointer to dynamically growing Text buffer
point	pointer to Point object

See also:

gaiaOutLinestringZ, gaiaOutPolygonZ

Remarks:

mainly intended for internal usage.

GAIAGEO_DECLARE void gaiaOutPolygonZ	(	gaiaOutBufferPtr	out_buf,
		gaiaPolygonPtr	polygon
	)

Encodes a WKT 3D Polygon [XYZ].

Parameters:

out_buf	pointer to dynamically growing Text buffer
polygon	pointer to Point object

See also:

gaiaOutPointZ, gaiaOutLinestringZ

Remarks:

mainly intended for internal usage.

GAIAGEO_DECLARE void gaiaOutSvg	(	gaiaOutBufferPtr	out_buf,
		gaiaGeomCollPtr	geom,
		int	relative,
		int	precision
	)

Encodes a Geometry object into SVG notation.

Parameters:

out_buf	pointer to dynamically growing Text buffer
geom	pointer to Geometry object
relative	flag: relative or absolute coordinates
precision	decimal digits to be used for coordinates

Note:

if relative is set to 1, then SVG relative coords will be used: in any other case SVG absolute coords will be assumed by default.

GAIAGEO_DECLARE void gaiaOutWkt	(	gaiaOutBufferPtr	out_buf,
		gaiaGeomCollPtr	geom
	)

Encodes a Geometry object into WKT notation.

Parameters:

out_buf	pointer to dynamically growing Text buffer
geom	pointer to Geometry object

See also:

gaiaParseWkt, gaiaOutWktStrict, gaiaParseEWKT, gaiaToEWKT

Note:

this function will apply 3D WKT encoding as internally intended by SpatiaLite: not necessarily intended by other OGC-like implementations.
Anyway, 2D WKT is surely standard and safely interoperable.

Examples:

demo2.c.

GAIAGEO_DECLARE void gaiaOutWktStrict	(	gaiaOutBufferPtr	out_buf,
		gaiaGeomCollPtr	geom,
		int	precision
	)

Encodes a Geometry object into strict 2D WKT notation.

Parameters:

out_buf	pointer to dynamically growing Text buffer
geom	pointer to Geometry object
precision	decimal digits to be used for coordinates

See also:

gaiaParseWkt, gaiaOutWkt, gaiaParseEWKT, gaiaToEWKT

Note:

this function will apply strict 2D WKT encoding, so to be surely standard and safely interoperable.
Dimensions will be automatically casted to 2D [XY] when required.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaParseEWKT

(

const unsigned char *

in_buffer

)

Creates a Geometry object from EWKT notation.

Parameters:

in_buffer

pointer to EWKT buffer

Returns:

the pointer to the newly created Geometry object: NULL on failure

See also:

gaiaParseWkt, gaiaOutWkt, gaiaOutWktStrict, gaiaToEWKT

Note:

you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaParseGeoJSON

(

const unsigned char *

in_buffer

)

Creates a Geometry object from GeoJSON notation.

Parameters:

in_buffer

pointer to GeoJSON buffer

Returns:

the pointer to the newly created Geometry object: NULL on failure

See also:

gaiaOutGeoJSON

Note:

you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaParseGml	(	const unsigned char *	in_buffer,
		sqlite3 *	sqlite_handle
	)

Creates a Geometry object from GML notation.

Parameters:

in_buffer	pointer to GML buffer
sqlite_handle	handle to current DB connection

Returns:

the pointer to the newly created Geometry object: NULL on failure

See also:

gaiaOutGml

Note:

you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaParseKml

(

const unsigned char *

in_buffer

)

Creates a Geometry object from KML notation.

Parameters:

in_buffer

pointer to KML buffer

Returns:

the pointer to the newly created Geometry object: NULL on failure

See also:

gaiaOutBareKml, gaiaOutFullKml

Note:

you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE gaiaGeomCollPtr gaiaParseWkt	(	const unsigned char *	in_buffer,
		short	type
	)

Creates a Geometry object from WKT notation.

Parameters:

in_buffer	pointer to WKT buffer
type	the expected Geometry Class Type if actual type defined in WKT doesn't corresponds to this, an error will be raised.

Returns:

the pointer to the newly created Geometry object: NULL on failure

See also:

gaiaOutWkt, gaiaOutWktStrict, gaiaParseEWKT, gaiaToEWKT

Note:

you are responsible to destroy (before or after) any allocated Geometry, unless you've passed ownership of the Geometry object to some further object: in this case destroying the higher order object will implicitly destroy any contained child object.

GAIAGEO_DECLARE int gaiaReadDbfEntity	(	gaiaDbfPtr	dbf,
		int	current_row,
		int *	deleted
	)

Reads a record from a DBF File object.

Parameters:

dbf	pointer to the DBF File object.
current_row	the row number identifying the record to be read.
deleted	on completion this variable will contain 0 if the record just read is valid: any other value if the record just read is marked as logically deleted.

Returns:

0 on failure: any other value on success.

See also:

gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfRead, gaiaOpenDbfWrite, gaiaFlushDbfHeader

Note:

on completion the DBF File First member will point to the linked list containing the corresponding data attributes [both data formats and values].

Remarks:

the DBF File object should be opened in read mode.

GAIAGEO_DECLARE int gaiaReadShpEntity	(	gaiaShapefilePtr	shp,
		int	current_row,
		int	srid
	)

Reads a feature from a Shapefile object.

Parameters:

shp	pointer to the Shapefile object.
current_row	the row number identifying the feature to be read.
srid	feature's SRID

Returns:

0 on failure: any other value on success.

See also:

gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpRead, gaiaOpenShpWrite, gaiaShpAnalyze, gaiaWriteShpEntity, gaiaFlushShpHeaders

Note:

on completion the Shapefile's Dbf member will contain the feature read:

• the Dbf->Geometry member will contain the corresponding Geometry
• and the Dbf->First member will point to the linked list containing the corresponding data attributes [both data formats and values].

Remarks:

the Shapefile object should be opened in read mode.

GAIAGEO_DECLARE void gaiaResetDbfEntity

(

gaiaDbfListPtr

list

)

Resets a DBF List object to its initial empty state.

Parameters:

list	pointer to the DBF List object.

See also:

gaiaFreeValue

Note:

any DBF Field associated to the List object will be reset to its initial empty state (i.e. no value at all).

GAIAGEO_DECLARE void gaiaSetDoubleValue	(	gaiaDbfFieldPtr	field,
		double	value
	)

Sets a DOUBLE current value for a DBF Field object.

Parameters:

field	pointer to DBF Field object.
value	double value to be set.

See also:

gaiaAllocDbfField, gaiaFreeDbfField, gaiaCloneDbfField, gaiaFreeValue, gaiaSetNullValue, gaiaSetIntValue, gaiaSetStrValue

GAIAGEO_DECLARE void gaiaSetIntValue	(	gaiaDbfFieldPtr	field,
		sqlite3_int64	value
	)

Sets an INTEGER current value for a DBF Field object.

Parameters:

field	pointer to DBF Field object.
value	integer value to be set.

See also:

gaiaAllocDbfField, gaiaFreeDbfField, gaiaCloneDbfField, gaiaFreeValue, gaiaSetNullValue, gaiaSetDoubleValue, gaiaSetStrValue

GAIAGEO_DECLARE void gaiaSetNullValue

(

gaiaDbfFieldPtr

field

)

Sets a NULL current value for a DBF Field object.

Parameters:

field

pointer to DBF Field object

See also:

gaiaAllocDbfField, gaiaFreeDbfField, gaiaCloneDbfField, gaiaFreeValue, gaiaSetIntValue, gaiaSetDoubleValue, gaiaSetStrValue

GAIAGEO_DECLARE void gaiaSetStrValue	(	gaiaDbfFieldPtr	field,
		char *	str
	)

Sets a TEXT current value for a DBF Field object.

Parameters:

field	pointer to DBF Field object.
str	text string value to be set.

See also:

gaiaAllocDbfField, gaiaFreeDbfField, gaiaCloneDbfField, gaiaFreeValue, gaiaSetNullValue, gaiaSetIntValue, gaiaSetDoubleValue

GAIAGEO_DECLARE void gaiaShpAnalyze

(

gaiaShapefilePtr

shp

)

Prescans a Shapefile object gathering informations.

Parameters:

shp	pointer to the Shapefile object.

See also:

gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpRead, gaiaOpenShpWrite, gaiaReadShpEntity, gaiaWriteShpEntity, gaiaFlushShpHeaders

Note:

on completion the Shapefile's EffectiveType will containt the Geometry type corresponding to features actually found.

Remarks:

the Shapefile object should be opened in read mode.

GAIAGEO_DECLARE gaiaTextReaderPtr gaiaTextReaderAlloc	(	const char *	path,
		char	field_separator,
		char	text_separator,
		char	decimal_separator,
		int	first_line_titles,
		const char *	encoding
	)

Creates a Text Reader object.

Parameters:

path	to the corresponding file-system file.
field_separator	the character acting as a separator between adjacent fields.
text_separator	the character used to quote text strings.
decimal_separator	the character used as a separator between integer and decimal digits for real numeric values.
first_line_titles	0 if the first line contains regular values: any other value if the first line contains column names.
encoding	GNU ICONV name identifying the input charset encoding.

Returns:

the pointer to the newly created Text Reader object: NULL on failure

See also:

gaiaTextReaderDestroy, gaiaTextReaderParse, gaiaTextReaderGetRow, gaiaTextReaderFetchField

Note:

you are responsible to destroy (before or after) any allocated Text Reader object.

GAIAGEO_DECLARE void gaiaTextReaderDestroy

(

gaiaTextReaderPtr

reader

)

Destroys a Text Reader object.

Parameters:

reader

pointer to Text Reader object.

See also:

gaiaTextReaderAlloc, gaiaTextReaderParse, gaiaTextReaderGetRow, gaiaTextReaderFetchField

GAIAGEO_DECLARE int gaiaTextReaderFetchField	(	gaiaTextReaderPtr	reader,
		int	field_num,
		int *	type,
		const char **	value
	)

Retrieves an individual field value from the current Line.

Parameters:

reader	pointer to Text Reader object.
field_num	relative field [aka column] index: first field has index 0.
type	on completion this variable will contain the value type.
value	on completion this variable will contain the current field value.

Returns:

0 on failure: any other value on success.

See also:

gaiaTextReaderAlloc, gaiaTextReaderDestroy, gaiaTextReaderParse, gaiaTextReaderGetRow

GAIAGEO_DECLARE int gaiaTextReaderGetRow	(	gaiaTextReaderPtr	reader,
		int	row_num
	)

Reads a line from a Text Reader object.

Parameters:

reader	pointer to Text Reader object.
row_num	the Line Number identifying the Line to be read.

Returns:

0 on failure: any other value on success.

See also:

gaiaTextReaderAlloc, gaiaTextReaderDestroy, gaiaTextReaderParse, gaiaTextReaderFetchField

Note:

this function will load the requested Line into the current buffer: you can then use gaiaTextReaderFetchField in order to retrieve any individual field [aka column] value.

GAIAGEO_DECLARE int gaiaTextReaderParse

(

gaiaTextReaderPtr

reader

)

Prescans the external file associated to a Text Reade object.

Parameters:

reader

pointer to Text Reader object.

Returns:

0 on failure: any other value on success.

See also:

gaiaTextReaderAlloc, gaiaTextReaderDestroy, gaiaTextReaderGetRow, gaiaTextReaderFetchField

Note:

this preliminary step is required so to ensure:

• file consistency: checking expected formatting rules.
• identifying the number / type / name of fields [aka columns].
• identifying the actual number of lines within the file.

GAIAGEO_DECLARE void gaiaToCompressedBlobWkb	(	gaiaGeomCollPtr	geom,
		unsigned char **	result,
		int *	size
	)

Creates a Compressed BLOB-Geometry corresponding to a Geometry object.

Parameters:

geom	pointer to the Geometry object.
result	on completion will containt a pointer to Compressed BLOB-Geometry: NULL on failure.
size	on completion this variable will contain the BLOB's size (in bytes)

See also:

gaiaFromSpatiaLiteBlobWkb, gaiaToSpatiaLiteBlobWkb

Note:

this function will apply compression to any Linestring / Ring found within the Geometry to be encoded.
the returned BLOB buffer corresponds to dynamically allocated memory: so you are responsible to free() it [unless SQLite will take care of memory cleanup via buffer binding].

GAIAGEO_DECLARE void gaiaToEWKB	(	gaiaOutBufferPtr	out_buf,
		gaiaGeomCollPtr	geom
	)

Encodes a Geometry object into EWKB notation.

Parameters:

out_buf	pointer to dynamically growing Text buffer
geom	pointer to Geometry object

See also:

gaiaFromWkb, gaiaToWkb, gaiaToHexWkb, gaiaFromEWKB, gaiaToEWKB

Note:

this function will produce strictly conformat EWKB; you can safely use this for PostGIS data exchange.

GAIAGEO_DECLARE void gaiaToEWKT	(	gaiaOutBufferPtr	out_buf,
		gaiaGeomCollPtr	geom
	)

Encodes a Geometry object into EWKT notation.

Parameters:

out_buf	pointer to dynamically growing Text buffer
geom	pointer to Geometry object

See also:

gaiaParseWkt, gaiaOutWkt, gaiaOutWktStrict, gaiaParseEWKT

Note:

this function will apply PostGIS own EWKT encoding.

GAIAGEO_DECLARE void gaiaToFgf	(	gaiaGeomCollPtr	geom,
		unsigned char **	result,
		int *	size,
		int	coord_dims
	)

Encodes a Geometry object into FGF notation.

Parameters:

geom	pointer to Geometry object
result	on completion will containt a pointer to the FGF buffer [BLOB]: NULL on failure.
size	on completion this variable will contain the BLOB's size (in bytes)
coord_dims	one of: GAIA_XY, GAIA_XY_Z, GAIA_XY_M, GAIA_XY_ZM

See also:

gaiaFromFgf

Note:

the returned BLOB buffer corresponds to dynamically allocated memory: so you are responsible to free() it [unless SQLite will take care of memory cleanup via buffer binding].

GAIAGEO_DECLARE char* gaiaToHexWkb

(

gaiaGeomCollPtr

geom

)

Encodes a Geometry object into (hex) WKB notation.

Parameters:

geom	pointer to Geometry object

Returns:

the pointer to a text buffer containing WKB translated into plain hexadecimal: NULL on failure.

See also:

gaiaFromWkb, gaiaToWkb, gaiaFromEWKB, gaiaToEWKB

Note:

the returned buffer corresponds to dynamically allocated memory: so you are responsible to free() it [unless SQLite will take care of memory cleanup via buffer binding].

GAIAGEO_DECLARE void gaiaToSpatiaLiteBlobWkb	(	gaiaGeomCollPtr	geom,
		unsigned char **	result,
		int *	size
	)

Creates a BLOB-Geometry corresponding to a Geometry object.

Parameters:

geom	pointer to the Geometry object.
result	on completion will containt a pointer to BLOB-Geometry: NULL on failure.
size	on completion this variable will contain the BLOB's size (in bytes)

See also:

gaiaFromSpatiaLiteBlobWkb, gaiaToCompressedBlobWkb

Note:

the BLOB buffer corresponds to dynamically allocated memory: so you are responsible to free() it [unless SQLite will take care of memory cleanup via buffer binding].

Examples:

demo3.c, and demo4.c.

GAIAGEO_DECLARE void gaiaToWkb	(	gaiaGeomCollPtr	geom,
		unsigned char **	result,
		int *	size
	)

Encodes a Geometry object into WKB notation.

Parameters:

geom	pointer to Geometry object
result	on completion will containt a pointer to the WKB buffer [BLOB]: NULL on failure.
size	on completion this variable will contain the BLOB's size (in bytes)

See also:

gaiaFromWkb, gaiaToHexWkb, gaiaFromEWKB, gaiaToEWKB

Note:

this function will apply 3D WKB encoding as internally intended by SpatiaLite: not necessarily intended by other OGC-like implementations.
Anyway, 2D WKB is surely standard and safely interoperable.
the returned BLOB buffer corresponds to dynamically allocated memory: so you are responsible to free() it [unless SQLite will take care of memory cleanup via buffer binding].

GAIAGEO_DECLARE int gaiaWriteDbfEntity	(	gaiaDbfPtr	dbf,
		gaiaDbfListPtr	entity
	)

Writes a record into a DBF File object.

Parameters:

dbf	pointer to the DBF File object.
entity	pointer to DBF List object containing Fields and corresponding values.

Returns:

0 on failure: any other value on success.

See also:

gaiaAllocDbf, gaiaFreeDbf, gaiaOpenDbfRead, gaiaOpenDbfWrite, gaiaReadDbfEntity, gaiaFlushDbfHeader

Remarks:

the DBF File object should be opened in write mode.

GAIAGEO_DECLARE int gaiaWriteShpEntity	(	gaiaShapefilePtr	shp,
		gaiaDbfListPtr	entity
	)

Writes a feature into a Shapefile object.

Parameters:

shp	pointer to the Shapefile object.
entity	pointer to DBF List object containing both Geometry and Field values.

Returns:

0 on failure: any other value on success.

See also:

gaiaAllocShapefile, gaiaFreeShapefile, gaiaOpenShpRead, gaiaOpenShpWrite, gaiaReadShpEntity, gaiaShpAnalyze, gaiaFlushShpHeaders

Remarks:

the Shapefile object should be opened in write mode.