org.tmatesoft.sqljet.core.internal

Interface ISqlJetVdbeMem

All Superinterfaces:

ISqlJetReleasable

All Known Implementing Classes:

SqlJetVdbeMem

public interface ISqlJetVdbeMem
extends ISqlJetReleasable

Method Summary

Methods

Modifier and Type	Method and Description
void	applyAffinity(SqlJetTypeAffinity affinity, SqlJetEncoding enc)
void	changeEncoding(SqlJetEncoding desiredEnc) If pMem is an object with a valid string representation, this routine ensures the internal encoding for the string representation is 'desiredEnc', one of SQLITE_UTF8, SQLITE_UTF16LE or SQLITE_UTF16BE.
ISqlJetVdbeMem	copy() Make a full copy of pFrom into pTo.
void	expandBlob() If the given Mem* has a zero-filled tail, turn it into an ordinary blob stored in dynamically allocated space.
void	fromBtree(ISqlJetBtreeCursor pCur, int offset, int amt, boolean key) Move data out of a btree key or data field and into a Mem structure.
java.util.Set<SqlJetVdbeMemFlags>	getFlags()
SqlJetValueType	getType()
void	grow(int n, boolean preserve) Make sure pMem->z points to a writable allocation of at least n bytes.
void	handleBom() This routine checks for a byte-order mark at the beginning of the UTF-16 string stored in *pMem.
void	integerAffinity() The MEM structure is already a MEM_Real.
void	integerify() Convert pMem to type integer.
long	intValue() Return some kind of integer value which is the best we can do at representing the value that *pMem describes as an integer.
boolean	isNull()
boolean	isTooBig() Return true if the Mem object contains a TEXT or BLOB that is too large - whose size exceeds SQLITE_MAX_LENGTH.
void	makeWriteable() Make the given Mem object MEM_Dyn.
ISqlJetVdbeMem	move() Transfer the contents of pFrom to pTo.
void	nulTerminate() Make sure the given Mem is nul terminated.
void	numerify() Convert pMem so that it has types MEM_Real or MEM_Int or both.
void	realify() Convert pMem so that it is of type MEM_Real.
double	realValue() Return the best representation of pMem that we can get into a double.
void	reset() Release any memory held by the Mem.
void	sanity() Perform various checks on the memory cell pMem.
void	setDouble(double val) Delete any previous value and set the value stored in *pMem to val, manifest type REAL.
void	setInt64(long val) Delete any previous value and set the value stored in *pMem to val, manifest type INTEGER.
void	setNull() Delete any previous value and set the value stored in *pMem to NULL.
void	setRowSet() Delete any previous value and set the value of pMem to be an empty boolean index.
void	setStr(ISqlJetMemoryPointer z, SqlJetEncoding enc) Change the value of a Mem to be a string or a BLOB.
void	setTypeFlag(SqlJetVdbeMemFlags f) Clear any existing type flags from a Mem and replace them with f
void	setZeroBlob(int n) Delete any previous value and set the value to be a BLOB of length n containing all zeros.
ISqlJetVdbeMem	shallowCopy(SqlJetVdbeMemFlags srcType) Make an shallow copy.
void	stringify(SqlJetEncoding enc) Add MEM_Str to the set of representations for the given Mem.
void	translate(SqlJetEncoding desiredEnc) This routine transforms the internal text encoding used by pMem to desiredEnc.
ISqlJetMemoryPointer	valueBlob() Converts the object V into a BLOB and then returns a pointer to the converted value.
int	valueBytes(SqlJetEncoding enc) Return the number of bytes in the sqlite3_value object assuming that it uses the encoding "enc"
ISqlJetMemoryPointer	valueText(SqlJetEncoding enc) This function is only available internally, it is not part of the external API.

Methods inherited from interface org.tmatesoft.sqljet.core.internal.ISqlJetReleasable

release

Method Detail

reset

void reset()

Release any memory held by the Mem. This may leave the Mem in an inconsistent state, for example with (Mem.z==0) and (Mem.type==SQLITE_TEXT).

changeEncoding

void changeEncoding(SqlJetEncoding desiredEnc)
                    throws SqlJetException

If pMem is an object with a valid string representation, this routine ensures the internal encoding for the string representation is 'desiredEnc', one of SQLITE_UTF8, SQLITE_UTF16LE or SQLITE_UTF16BE. If pMem is not a string object, or the encoding of the string representation is already stored using the requested encoding, then this routine is a no-op. SQLITE_OK is returned if the conversion is successful (or not required). SQLITE_NOMEM may be returned if a malloc() fails during conversion between formats.

Parameters:

enc -

Throws:

SqlJetException

translate

void translate(SqlJetEncoding desiredEnc)
               throws SqlJetException

This routine transforms the internal text encoding used by pMem to desiredEnc. It is an error if the string is already of the desired encoding, or if *pMem does not contain a string value.

Parameters:

desiredEnc -

Throws:

SqlJetException

handleBom

void handleBom()

This routine checks for a byte-order mark at the beginning of the UTF-16 string stored in *pMem. If one is present, it is removed and the encoding of the Mem adjusted. This routine does not do any byte-swapping, it just sets Mem.enc appropriately. The allocation (static, dynamic etc.) and encoding of the Mem may be changed by this function.

expandBlob

void expandBlob()

If the given Mem* has a zero-filled tail, turn it into an ordinary blob stored in dynamically allocated space.

valueText

ISqlJetMemoryPointer valueText(SqlJetEncoding enc)
                               throws SqlJetException

This function is only available internally, it is not part of the external API. It works in a similar way to sqlite3_value_text(), except the data returned is in the encoding specified by the second parameter, which must be one of SQLITE_UTF16BE, SQLITE_UTF16LE or SQLITE_UTF8. (2006-02-16:) The enc value can be or-ed with SQLITE_UTF16_ALIGNED. If that is the case, then the result must be aligned on an even byte boundary.

Parameters:

enc -

Returns:

Throws:

SqlJetException

grow

void grow(int n,
        boolean preserve)

Make sure pMem->z points to a writable allocation of at least n bytes. If the memory cell currently contains string or blob data and the third argument passed to this function is true, the current content of the cell is preserved. Otherwise, it may be discarded. This function sets the MEM_Dyn flag and clears any xDel callback. It also clears MEM_Ephem and MEM_Static. If the preserve flag is not set, Mem.n is zeroed.

Parameters:

n -

preserve -

fromBtree

void fromBtree(ISqlJetBtreeCursor pCur,
             int offset,
             int amt,
             boolean key)
               throws SqlJetException

Move data out of a btree key or data field and into a Mem structure. The data or key is taken from the entry that pCur is currently pointing to. offset and amt determine what portion of the data or key to retrieve. key is true to get the key or false to get data. The result is written into the pMem element. The pMem structure is assumed to be uninitialized. Any prior content is overwritten without being freed. If this routine fails for any reason (malloc returns NULL or unable to read from the disk) then the pMem is left in an inconsistent state.

Parameters:

pCur -

offset - Offset from the start of data to return bytes from.

amt - Number of bytes to return.

key - If true, retrieve from the btree key, not data.

Throws:

SqlJetException

makeWriteable

void makeWriteable()

Make the given Mem object MEM_Dyn. In other words, make it so that any TEXT or BLOB content is stored in memory obtained from malloc(). In this way, we know that the memory is safe to be overwritten or altered.

intValue

long intValue()

Return some kind of integer value which is the best we can do at representing the value that *pMem describes as an integer. If pMem is an integer, then the value is exact. If pMem is a floating-point then the value returned is the integer part. If pMem is a string or blob, then we make an attempt to convert it into a integer and return that. If pMem is NULL, return 0. If pMem is a string, its encoding might be changed.

setNull

void setNull()

Delete any previous value and set the value stored in *pMem to NULL.

setStr

void setStr(ISqlJetMemoryPointer z,
          SqlJetEncoding enc)
            throws SqlJetException

Change the value of a Mem to be a string or a BLOB. The memory management strategy depends on the value of the xDel parameter. If the value passed is SQLITE_TRANSIENT, then the string is copied into a (possibly existing) buffer managed by the Mem structure. Otherwise, any existing buffer is freed and the pointer copied.

Throws:

SqlJetException

setInt64

void setInt64(long val)

Delete any previous value and set the value stored in *pMem to val, manifest type INTEGER.

nulTerminate

void nulTerminate()

Make sure the given Mem is nul terminated.

stringify

void stringify(SqlJetEncoding enc)
               throws SqlJetException

Add MEM_Str to the set of representations for the given Mem. Numbers are converted using sqlite3_snprintf(). Converting a BLOB to a string is a no-op. Existing representations MEM_Int and MEM_Real are *not* invalidated. A MEM_Null value will never be passed to this function. This function is used for converting values to text for returning to the user (i.e. via sqlite3_value_text()), or for ensuring that values to be used as btree keys are strings. In the former case a NULL pointer is returned the user and the later is an internal programming error.

Parameters:

enc -

Throws:

SqlJetException

realValue

double realValue()

Return the best representation of pMem that we can get into a double. If pMem is already a double or an integer, return its value. If it is a string or blob, try to convert it to a double. If it is a NULL, return 0.0.

integerAffinity

void integerAffinity()

The MEM structure is already a MEM_Real. Try to also make it a MEM_Int if we can.

integerify

void integerify()

Convert pMem to type integer. Invalidate any prior representations.

realify

void realify()

Convert pMem so that it is of type MEM_Real. Invalidate any prior representations.

numerify

void numerify()

Convert pMem so that it has types MEM_Real or MEM_Int or both. Invalidate any prior representations.

setZeroBlob

void setZeroBlob(int n)

Delete any previous value and set the value to be a BLOB of length n containing all zeros.

setDouble

void setDouble(double val)

Delete any previous value and set the value stored in *pMem to val, manifest type REAL.

setRowSet

void setRowSet()

Delete any previous value and set the value of pMem to be an empty boolean index.

isTooBig

boolean isTooBig()

Return true if the Mem object contains a TEXT or BLOB that is too large - whose size exceeds SQLITE_MAX_LENGTH.

shallowCopy

ISqlJetVdbeMem shallowCopy(SqlJetVdbeMemFlags srcType)
                           throws SqlJetException

Make an shallow copy. The pFrom->z field is not duplicated. If pFrom->z is used, then pTo->z points to the same thing as pFrom->z and flags gets srcType (either MEM_Ephem or MEM_Static).

Parameters:

srcType -

Throws:

SqlJetException

copy

ISqlJetVdbeMem copy()
                    throws SqlJetException

Make a full copy of pFrom into pTo. Prior contents of pTo are freed before the copy is made.

Throws:

SqlJetException

move

ISqlJetVdbeMem move()
                    throws SqlJetException

Transfer the contents of pFrom to pTo. Any existing value in pTo is freed. If pFrom contains ephemeral data, a copy is made. pFrom contains an SQL NULL when this routine returns.

Throws:

SqlJetException

sanity

void sanity()

Perform various checks on the memory cell pMem. An assert() will fail if pMem is internally inconsistent.

valueBytes

int valueBytes(SqlJetEncoding enc)
               throws SqlJetException

Return the number of bytes in the sqlite3_value object assuming that it uses the encoding "enc"

Throws:

SqlJetException

setTypeFlag

void setTypeFlag(SqlJetVdbeMemFlags f)

Clear any existing type flags from a Mem and replace them with f

Parameters:

real -

getFlags

java.util.Set<SqlJetVdbeMemFlags> getFlags()

isNull

boolean isNull()

Returns:

getType

SqlJetValueType getType()

Returns:

valueBlob

ISqlJetMemoryPointer valueBlob()
                               throws SqlJetException

Converts the object V into a BLOB and then returns a pointer to the converted value.

Returns:

Throws:

SqlJetException

applyAffinity

void applyAffinity(SqlJetTypeAffinity affinity,
                 SqlJetEncoding enc)
                   throws SqlJetException

Parameters:

affinity -

enc -

Throws:

SqlJetException