src/headers/spatialite/gaiaaux.h File Reference

Auxiliary/helper functions. More...

Go to the source code of this file.

Defines
#define	GAIA_SQL_SINGLE_QUOTE   1001
	SQL single quoted string (text constant)
#define	GAIA_SQL_DOUBLE_QUOTE   1002
	SQL double quoted string (SQL name)
Functions
GAIAAUX_DECLARE const char *	gaiaGetLocaleCharset (void)
	Retrieves the Locale Charset.
GAIAAUX_DECLARE int	gaiaConvertCharset (char **buf, const char *fromCs, const char *toCs)
	Converts a text string from one charset to another.
GAIAAUX_DECLARE void *	gaiaCreateUTF8Converter (const char *fromCS)
	Creates a persistent UTF8 converter object.
GAIAAUX_DECLARE void	gaiaFreeUTF8Converter (void *cvtCS)
	Destroys an UTF8 converter object.
GAIAAUX_DECLARE char *	gaiaConvertToUTF8 (void *cvtCS, const char *buf, int len, int *err)
	Converts a text string to UTF8.
GAIAAUX_DECLARE int	gaiaIsReservedSqliteName (const char *name)
	Checks if a name is a reserved SQLite name.
GAIAAUX_DECLARE int	gaiaIsReservedSqlName (const char *name)
	Checks if a name is a reserved SQL name.
GAIAAUX_DECLARE int	gaiaIllegalSqlName (const char *name)
	Checks if a name is an illegal SQL name.
GAIAAUX_DECLARE char *	gaiaSingleQuotedSql (const char *value)
	Properly formats an SQL text constant.
GAIAAUX_DECLARE char *	gaiaDoubleQuotedSql (const char *value)
	Properly formats an SQL name.
GAIAAUX_DECLARE char *	gaiaQuotedSql (const char *value, int quote)
	Properly formats an SQL generic string.
GAIAAUX_DECLARE void	gaiaCleanSqlString (char *value)
	deprecated function

---

Detailed Description

Auxiliary/helper functions.

---

Function Documentation

GAIAAUX_DECLARE void gaiaCleanSqlString

(

char *

value

)

deprecated function

Parameters:

value

the string to be formatted

See also:

gaiaQuotedSql

Note:

this function is still supported simply for backward compatibility. it's intrinsically unsafe (passing huge strings potentially leads to buffer overflows) and you are strongly encouraged to use gaiaQuotedSql() as a safest replacement.

GAIAAUX_DECLARE int gaiaConvertCharset	(	char **	buf,
		const char *	fromCs,
		const char *	toCs
	)

Converts a text string from one charset to another.

Parameters:

buf	the text string to be converted
fromCs	the GNU ICONV name identifying the input charset
toCs	the GNU ICONV name identifying the output charset

Returns:

0 on failure, any other value on success.

Note:

this function uses an internal buffer limited to 64KB; so it's not safe passing extremely huge-sized text string.

GAIAAUX_DECLARE char* gaiaConvertToUTF8	(	void *	cvtCS,
		const char *	buf,
		int	len,
		int *	err
	)

Converts a text string to UTF8.

Parameters:

cvtCS	the handle identifying the UTF8 convert object (returned by a previous call to gaiaCreateUTF8Converter).
buf	the input text string
len	length (in bytes) of input string
err	on completion will contain 0 on success, any other value on failure

Returns:

the null-terminated UTF8 encoded string: NULL on failure

See also:

gaiaCreateUTF8Converter, gaiaFreeUTF8Converter

Note:

this function can safely handle strings of arbitrary length, and will return the converted string into a dynamically allocated buffer created by malloc(). You are required to explicitly free() any string returned by this function.

GAIAAUX_DECLARE void* gaiaCreateUTF8Converter

(

const char *

fromCS

)

Creates a persistent UTF8 converter object.

Parameters:

fromCS

the GNU ICONV name identifying the input charset

Returns:

the handle of the converter object, or NULL on failure

See also:

gaiaFreeUTF8Converter

Note:

you must properly destroy the converter object when it isn't any longer used.

GAIAAUX_DECLARE char* gaiaDoubleQuotedSql

(

const char *

value

)

Properly formats an SQL name.

Parameters:

value

the SQL name to be formatted

Returns:

the formatted string: NULL on failure

See also:

gaiaQuotedSql

Note:

this function simply is a convenience method corresponding to: gaiaQuotedSQL(value, GAIA_SQL_DOUBLE_QUOTE);

Remarks:

passing a string like "Sant\"Andrea" will return "Sant""Andrea"

GAIAAUX_DECLARE void gaiaFreeUTF8Converter

(

void *

cvtCS

)

Destroys an UTF8 converter object.

Parameters:

cvtCS

the handle identifying the UTF8 convert object (returned by a previous call to gaiaCreateUTF8Converter).

See also:

gaiaCreateUTF8Converter

GAIAAUX_DECLARE const char* gaiaGetLocaleCharset

(

void

)

Retrieves the Locale Charset.

Returns:

the GNU ICONV name identifying the locale charset

GAIAAUX_DECLARE int gaiaIllegalSqlName

(

const char *

name

)

Checks if a name is an illegal SQL name.

Parameters:

name	the name to be checked

Returns:

0 if no: any other value if yes

See also:

gaiaIsReservedSqliteName, gaiaIsReservedSqlName

GAIAAUX_DECLARE int gaiaIsReservedSqliteName

(

const char *

name

)

Checks if a name is a reserved SQLite name.

Parameters:

name	the name to be checked

Returns:

0 if no: any other value if yes

See also:

gaiaIsReservedSqlName, gaiaIllegalSqlName

GAIAAUX_DECLARE int gaiaIsReservedSqlName

(

const char *

name

)

Checks if a name is a reserved SQL name.

Parameters:

name	the name to be checked

Returns:

0 if no: any other value if yes

See also:

gaiaIsReservedSqliteName, gaiaIllegalSqlName

GAIAAUX_DECLARE char* gaiaQuotedSql	(	const char *	value,
		int	quote
	)

Properly formats an SQL generic string.

Parameters:

value	the string to be formatted
quote	GAIA_SQL_SINGLE_QUOTE or GAIA_SQL_DOUBLE_QUOTE

Returns:

the formatted string: NULL on failure

See also:

gaiaSingleQuotedSql, gaiaDoubleQuotedSql

Note:

this function can safely handle strings of arbitrary length, and will return the formatted string into a dynamically allocated buffer created by malloc(). You are required to explicitly free() any string returned by this function.

GAIAAUX_DECLARE char* gaiaSingleQuotedSql

(

const char *

value

)

Properly formats an SQL text constant.

Parameters:

value

the text string to be formatted

Returns:

the formatted string: NULL on failure

See also:

gaiaQuotedSql

Note:

this function simply is a convenience method corresponding to: gaiaQuotedSQL(value, GAIA_SQL_SINGLE_QUOTE);

Remarks:

passing a string like "Sant'Andrea" will return 'Sant''Andrea'