Class SqlJetVdbeMem

  • All Implemented Interfaces:
    java.lang.Cloneable, ISqlJetReleasable, ISqlJetVdbeMem

    public class SqlJetVdbeMem
    extends SqlJetCloneable
    implements ISqlJetVdbeMem
    Internally, the vdbe manipulates nearly all SQL values as Mem structures. Each Mem struct may cache multiple representations (string, integer etc.) of the same value. A value (and therefore Mem structure) has the following properties: Each value has a manifest type. The manifest type of the value stored in a Mem struct is returned by the MemType(Mem*) macro. The type is one of SQLITE_NULL, SQLITE_INTEGER, SQLITE_REAL, SQLITE_TEXT or SQLITE_BLOB.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void applyAffinity​(SqlJetTypeAffinity affinity, SqlJetEncoding enc)
      Processing is determine by the affinity parameter: AFF_INTEGER: AFF_REAL: AFF_NUMERIC: Try to convert value to an integer representation or a floating-point representation if an integer representation is not possible.
      void applyNumericAffinity()
      Try to convert a value into a numeric representation if we can do so without loss of information.
      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.
      static int compare​(SqlJetVdbeMem pMem1, SqlJetVdbeMem pMem2, ISqlJetCollSeq pColl)
      Compare the values contained by the two memory cells, returning negative, zero or positive if pMem1 is less than, equal to, or greater than pMem2.
      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.
      static SqlJetVdbeMem obtainInstance()  
      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 release()  
      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 class java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • instanceCounter

        public static long instanceCounter
    • Method Detail

      • reset

        public void reset()
        Description copied from interface: ISqlJetVdbeMem
        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).
        Specified by:
        reset in interface ISqlJetVdbeMem
      • compare

        public static int compare​(SqlJetVdbeMem pMem1,
                                  SqlJetVdbeMem pMem2,
                                  ISqlJetCollSeq pColl)
                           throws SqlJetException
        Compare the values contained by the two memory cells, returning negative, zero or positive if pMem1 is less than, equal to, or greater than pMem2. Sorting order is NULL's first, followed by numbers (integers and reals) sorted numerically, followed by text ordered by the collating sequence pColl and finally blob's ordered by memcmp().Two NULL values are considered equal by this function.
        Throws:
        SqlJetException
      • valueText

        public ISqlJetMemoryPointer valueText​(SqlJetEncoding enc)
                                       throws SqlJetException
        Description copied from interface: ISqlJetVdbeMem
        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.
        Specified by:
        valueText in interface ISqlJetVdbeMem
        Returns:
        Throws:
        SqlJetException
      • stringify

        public void stringify​(SqlJetEncoding enc)
                       throws SqlJetException
        Description copied from interface: ISqlJetVdbeMem
        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.
        Specified by:
        stringify in interface ISqlJetVdbeMem
        Throws:
        SqlJetException
      • grow

        public void grow​(int n,
                         boolean preserve)
        Description copied from interface: ISqlJetVdbeMem
        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.
        Specified by:
        grow in interface ISqlJetVdbeMem
      • changeEncoding

        public void changeEncoding​(SqlJetEncoding desiredEnc)
                            throws SqlJetException
        Description copied from interface: ISqlJetVdbeMem
        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.
        Specified by:
        changeEncoding in interface ISqlJetVdbeMem
        Throws:
        SqlJetException
      • translate

        public void translate​(SqlJetEncoding desiredEnc)
                       throws SqlJetException
        Description copied from interface: ISqlJetVdbeMem
        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.
        Specified by:
        translate in interface ISqlJetVdbeMem
        Throws:
        SqlJetException
      • expandBlob

        public void expandBlob()
        Description copied from interface: ISqlJetVdbeMem
        If the given Mem* has a zero-filled tail, turn it into an ordinary blob stored in dynamically allocated space.
        Specified by:
        expandBlob in interface ISqlJetVdbeMem
      • fromBtree

        public void fromBtree​(ISqlJetBtreeCursor pCur,
                              int offset,
                              int amt,
                              boolean key)
                       throws SqlJetException
        Description copied from interface: ISqlJetVdbeMem
        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.
        Specified by:
        fromBtree in interface ISqlJetVdbeMem
        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

        public void makeWriteable()
        Description copied from interface: ISqlJetVdbeMem
        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.
        Specified by:
        makeWriteable in interface ISqlJetVdbeMem
      • intValue

        public long intValue()
        Description copied from interface: ISqlJetVdbeMem
        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.
        Specified by:
        intValue in interface ISqlJetVdbeMem
      • setNull

        public void setNull()
        Description copied from interface: ISqlJetVdbeMem
        Delete any previous value and set the value stored in *pMem to NULL.
        Specified by:
        setNull in interface ISqlJetVdbeMem
      • setStr

        public void setStr​(ISqlJetMemoryPointer z,
                           SqlJetEncoding enc)
                    throws SqlJetException
        Description copied from interface: ISqlJetVdbeMem
        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.
        Specified by:
        setStr in interface ISqlJetVdbeMem
        Throws:
        SqlJetException
      • setInt64

        public void setInt64​(long val)
        Description copied from interface: ISqlJetVdbeMem
        Delete any previous value and set the value stored in *pMem to val, manifest type INTEGER.
        Specified by:
        setInt64 in interface ISqlJetVdbeMem
      • realValue

        public double realValue()
        Description copied from interface: ISqlJetVdbeMem
        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.
        Specified by:
        realValue in interface ISqlJetVdbeMem
      • integerAffinity

        public void integerAffinity()
        Description copied from interface: ISqlJetVdbeMem
        The MEM structure is already a MEM_Real. Try to also make it a MEM_Int if we can.
        Specified by:
        integerAffinity in interface ISqlJetVdbeMem
      • integerify

        public void integerify()
        Description copied from interface: ISqlJetVdbeMem
        Convert pMem to type integer. Invalidate any prior representations.
        Specified by:
        integerify in interface ISqlJetVdbeMem
      • realify

        public void realify()
        Description copied from interface: ISqlJetVdbeMem
        Convert pMem so that it is of type MEM_Real. Invalidate any prior representations.
        Specified by:
        realify in interface ISqlJetVdbeMem
      • numerify

        public void numerify()
        Description copied from interface: ISqlJetVdbeMem
        Convert pMem so that it has types MEM_Real or MEM_Int or both. Invalidate any prior representations.
        Specified by:
        numerify in interface ISqlJetVdbeMem
      • setZeroBlob

        public void setZeroBlob​(int n)
        Description copied from interface: ISqlJetVdbeMem
        Delete any previous value and set the value to be a BLOB of length n containing all zeros.
        Specified by:
        setZeroBlob in interface ISqlJetVdbeMem
      • setDouble

        public void setDouble​(double val)
        Description copied from interface: ISqlJetVdbeMem
        Delete any previous value and set the value stored in *pMem to val, manifest type REAL.
        Specified by:
        setDouble in interface ISqlJetVdbeMem
      • setRowSet

        public void setRowSet()
        Description copied from interface: ISqlJetVdbeMem
        Delete any previous value and set the value of pMem to be an empty boolean index.
        Specified by:
        setRowSet in interface ISqlJetVdbeMem
      • isTooBig

        public boolean isTooBig()
        Description copied from interface: ISqlJetVdbeMem
        Return true if the Mem object contains a TEXT or BLOB that is too large - whose size exceeds SQLITE_MAX_LENGTH.
        Specified by:
        isTooBig in interface ISqlJetVdbeMem
      • sanity

        public void sanity()
        Description copied from interface: ISqlJetVdbeMem
        Perform various checks on the memory cell pMem. An assert() will fail if pMem is internally inconsistent.
        Specified by:
        sanity in interface ISqlJetVdbeMem
      • handleBom

        public void handleBom()
        Description copied from interface: ISqlJetVdbeMem
        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.
        Specified by:
        handleBom in interface ISqlJetVdbeMem
      • applyAffinity

        public void applyAffinity​(SqlJetTypeAffinity affinity,
                                  SqlJetEncoding enc)
                           throws SqlJetException
        Processing is determine by the affinity parameter:
        • AFF_INTEGER:
        • AFF_REAL:
        • AFF_NUMERIC:
        Try to convert value to an integer representation or a floating-point representation if an integer representation is not possible. Note that the integer representation is always preferred, even if the affinity is REAL, because an integer representation is more space efficient on disk.
        • AFF_TEXT:
        Convert value to a text representation.
        • AFF_NONE:
        No-op. value is unchanged.
        Specified by:
        applyAffinity in interface ISqlJetVdbeMem
        Parameters:
        affinity - The affinity to be applied
        enc - Use this text encoding
        Throws:
        SqlJetException
      • applyNumericAffinity

        public void applyNumericAffinity()
                                  throws SqlJetException
        Try to convert a value into a numeric representation if we can do so without loss of information. In other words, if the string looks like a number, convert it into a number. If it does not look like a number, leave it alone.
        Throws:
        SqlJetException