System.Data.SQLite
Check-in [3fbdd30433]
Not logged in

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Document the SQLiteString class. In the SQLiteString.ProbeForUtf8ByteLength method, make sure the limit is greater than zero.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | virtualTables
Files: files | file ages | folders
SHA1: 3fbdd30433204f882229201857b6f80ba19a071a
User & Date: mistachkin 2013-06-25 07:44:13
Context
2013-06-25
08:24
Move byte array handling methods to the SQLiteBytes class. Remove superfluous ValueArrayFromSizeAndIntPtr method from the SQLiteMarshal class. More work on docs. check-in: 75dd5c847a user: mistachkin tags: virtualTables
07:44
Document the SQLiteString class. In the SQLiteString.ProbeForUtf8ByteLength method, make sure the limit is greater than zero. check-in: 3fbdd30433 user: mistachkin tags: virtualTables
06:58
Document the SQLiteMemory class. check-in: 3b2c842774 user: mistachkin tags: virtualTables
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to System.Data.SQLite/SQLiteModule.cs.

  3493   3493   
  3494   3494       ///////////////////////////////////////////////////////////////////////////
  3495   3495   
  3496   3496       #region SQLiteString Static Class
  3497   3497       internal static class SQLiteString
  3498   3498       {
  3499   3499           #region Private Constants
         3500  +        /// <summary>
         3501  +        /// This is the maximum possible length for the native UTF-8 encoded
         3502  +        /// strings used with the SQLite core library.
         3503  +        /// </summary>
  3500   3504           private static int ThirtyBits = 0x3fffffff;
         3505  +
         3506  +        ///////////////////////////////////////////////////////////////////////
         3507  +
         3508  +        /// <summary>
         3509  +        /// This is the <see cref="Encoding" /> object instance used to handle
         3510  +        /// conversions from/to UTF-8.
         3511  +        /// </summary>
  3501   3512           private static readonly Encoding Utf8Encoding = Encoding.UTF8;
  3502   3513           #endregion
  3503   3514   
  3504   3515           ///////////////////////////////////////////////////////////////////////
  3505   3516   
  3506   3517           #region UTF-8 Encoding Helper Methods
         3518  +        /// <summary>
         3519  +        /// Converts the specified managed string into the UTF-8 encoding and
         3520  +        /// returns the array of bytes containing its representation in that
         3521  +        /// encoding.
         3522  +        /// </summary>
         3523  +        /// <param name="value">
         3524  +        /// The managed string to convert.
         3525  +        /// </param>
         3526  +        /// <returns>
         3527  +        /// The array of bytes containing the representation of the managed
         3528  +        /// string in the UTF-8 encoding or null upon failure.
         3529  +        /// </returns>
  3507   3530           public static byte[] GetUtf8BytesFromString(
  3508   3531               string value
  3509   3532               )
  3510   3533           {
  3511   3534               if (value == null)
  3512   3535                   return null;
  3513   3536   
  3514   3537               return Utf8Encoding.GetBytes(value);
  3515   3538           }
  3516   3539   
  3517   3540           ///////////////////////////////////////////////////////////////////////
  3518   3541   
         3542  +        /// <summary>
         3543  +        /// Converts the specified array of bytes representing a string in the
         3544  +        /// UTF-8 encoding and returns a managed string.
         3545  +        /// </summary>
         3546  +        /// <param name="bytes">
         3547  +        /// The array of bytes to convert.
         3548  +        /// </param>
         3549  +        /// <returns>
         3550  +        /// The managed string or null upon failure.
         3551  +        /// </returns>
  3519   3552           public static string GetStringFromUtf8Bytes(
  3520   3553               byte[] bytes
  3521   3554               )
  3522   3555           {
  3523   3556               if (bytes == null)
  3524   3557                   return null;
  3525   3558   
................................................................................
  3530   3563   #endif
  3531   3564           }
  3532   3565           #endregion
  3533   3566   
  3534   3567           ///////////////////////////////////////////////////////////////////////
  3535   3568   
  3536   3569           #region UTF-8 String Helper Methods
         3570  +        /// <summary>
         3571  +        /// Probes a native pointer to a string in the UTF-8 encoding for its
         3572  +        /// terminating NUL character, within the specified length limit.
         3573  +        /// </summary>
         3574  +        /// <param name="pValue">
         3575  +        /// The native NUL-terminated string pointer.
         3576  +        /// </param>
         3577  +        /// <param name="limit">
         3578  +        /// The maximum length of the native string, in bytes.
         3579  +        /// </param>
         3580  +        /// <returns>
         3581  +        /// The length of the native string, in bytes -OR- zero if the length
         3582  +        /// could not be determined.
         3583  +        /// </returns>
  3537   3584           public static int ProbeForUtf8ByteLength(
  3538   3585               IntPtr pValue,
  3539   3586               int limit
  3540   3587               )
  3541   3588           {
  3542   3589               int length = 0;
  3543   3590   
  3544         -            if (pValue != IntPtr.Zero)
         3591  +            if ((pValue != IntPtr.Zero) && (limit > 0))
  3545   3592               {
  3546   3593                   do
  3547   3594                   {
  3548   3595                       if (Marshal.ReadByte(pValue, length) == 0)
  3549   3596                           break;
  3550   3597   
  3551   3598                       if (length >= limit)
................................................................................
  3556   3603               }
  3557   3604   
  3558   3605               return length;
  3559   3606           }
  3560   3607   
  3561   3608           ///////////////////////////////////////////////////////////////////////
  3562   3609   
         3610  +        /// <summary>
         3611  +        /// Converts the specified native NUL-terminated UTF-8 string pointer
         3612  +        /// into a managed string.
         3613  +        /// </summary>
         3614  +        /// <param name="pValue">
         3615  +        /// The native NUL-terminated UTF-8 string pointer.
         3616  +        /// </param>
         3617  +        /// <returns>
         3618  +        /// The managed string or null upon failure.
         3619  +        /// </returns>
  3563   3620           public static string StringFromUtf8IntPtr(
  3564   3621               IntPtr pValue
  3565   3622               )
  3566   3623           {
  3567   3624               return StringFromUtf8IntPtr(pValue,
  3568   3625                   ProbeForUtf8ByteLength(pValue, ThirtyBits));
  3569   3626           }
  3570   3627   
  3571   3628           ///////////////////////////////////////////////////////////////////////
  3572   3629   
         3630  +        /// <summary>
         3631  +        /// Converts the specified native UTF-8 string pointer of the specified
         3632  +        /// length into a managed string.
         3633  +        /// </summary>
         3634  +        /// <param name="pValue">
         3635  +        /// The native UTF-8 string pointer.
         3636  +        /// </param>
         3637  +        /// <param name="length">
         3638  +        /// The length of the native string, in bytes.
         3639  +        /// </param>
         3640  +        /// <returns>
         3641  +        /// The managed string or null upon failure.
         3642  +        /// </returns>
  3573   3643           public static string StringFromUtf8IntPtr(
  3574   3644               IntPtr pValue,
  3575   3645               int length
  3576   3646               )
  3577   3647           {
  3578   3648               if (pValue == IntPtr.Zero)
  3579   3649                   return null;
................................................................................
  3588   3658               }
  3589   3659   
  3590   3660               return String.Empty;
  3591   3661           }
  3592   3662   
  3593   3663           ///////////////////////////////////////////////////////////////////////
  3594   3664   
         3665  +        /// <summary>
         3666  +        /// Converts the specified managed string into a native NUL-terminated
         3667  +        /// UTF-8 string pointer using memory obtained from the SQLite core
         3668  +        /// library.
         3669  +        /// </summary>
         3670  +        /// <param name="value">
         3671  +        /// The managed string to convert.
         3672  +        /// </param>
         3673  +        /// <returns>
         3674  +        /// The native NUL-terminated UTF-8 string pointer or
         3675  +        /// <see cref="IntPtr.Zero" /> upon failure.
         3676  +        /// </returns>
  3595   3677           public static IntPtr Utf8IntPtrFromString(
  3596   3678               string value
  3597   3679               )
  3598   3680           {
  3599   3681               if (value == null)
  3600   3682                   return IntPtr.Zero;
  3601   3683   
................................................................................
  3618   3700               return result;
  3619   3701           }
  3620   3702           #endregion
  3621   3703   
  3622   3704           ///////////////////////////////////////////////////////////////////////
  3623   3705   
  3624   3706           #region UTF-8 String Array Helper Methods
         3707  +        /// <summary>
         3708  +        /// Converts an array of native NUL-terminated UTF-8 string pointers
         3709  +        /// into an array of managed strings.
         3710  +        /// </summary>
         3711  +        /// <param name="pValues">
         3712  +        /// The array of native NUL-terminated UTF-8 string pointers.
         3713  +        /// </param>
         3714  +        /// <returns>
         3715  +        /// The array of managed strings or null upon failure.
         3716  +        /// </returns>
  3625   3717           public static string[] StringArrayFromUtf8IntPtrArray(
  3626   3718               IntPtr[] pValues
  3627   3719               )
  3628   3720           {
  3629   3721               if (pValues == null)
  3630   3722                   return null;
  3631   3723   
................................................................................
  3635   3727                   result[index] = StringFromUtf8IntPtr(pValues[index]);
  3636   3728   
  3637   3729               return result;
  3638   3730           }
  3639   3731   
  3640   3732           ///////////////////////////////////////////////////////////////////////
  3641   3733   
         3734  +        /// <summary>
         3735  +        /// Converts an array of managed strings into an array of native
         3736  +        /// NUL-terminated UTF-8 string pointers.
         3737  +        /// </summary>
         3738  +        /// <param name="values">
         3739  +        /// The array of managed strings to convert.
         3740  +        /// </param>
         3741  +        /// <returns>
         3742  +        /// The array of native NUL-terminated UTF-8 string pointers or null
         3743  +        /// upon failure.
         3744  +        /// </returns>
  3642   3745           public static IntPtr[] Utf8IntPtrArrayFromStringArray(
  3643   3746               string[] values
  3644   3747               )
  3645   3748           {
  3646   3749               if (values == null)
  3647   3750                   return null;
  3648   3751