glibmm r529 - in trunk: . glib/src

[murrayc svn gnome org]

Author: murrayc
Date: Sun Jan 20 18:16:54 2008
New Revision: 529
URL: http://svn.gnome.org/viewvc/glibmm?rev=529&view=rev

Log:
2008-01-20  Murray Cumming  <murrayc murrayc com>

* glib/src/checksum.ccg:
* glib/src/checksum.hg: Added class documentation. Corrected constructor 
documentation and added operator bool() to check for a failure in the 
constructor.

Modified:
   trunk/ChangeLog
   trunk/glib/src/checksum.ccg
   trunk/glib/src/checksum.hg

Modified: trunk/glib/src/checksum.ccg
==============================================================================
--- trunk/glib/src/checksum.ccg	(original)
+++ trunk/glib/src/checksum.ccg	Sun Jan 20 18:16:54 2008
@@ -30,10 +30,14 @@
 {
 }
 
+Checksum::operator bool() const
+{
+  return gobject_ != 0;
+}
 
-gssize Checksum::get_length(ChecksumType type)
+gssize Checksum::get_length(ChecksumType checksum_type)
 {
-  return g_checksum_type_get_length((GChecksumType)type);
+  return g_checksum_type_get_length((GChecksumType)checksum_type);
 }
 
 std::string Checksum::compute_checksum(ChecksumType type, const std::string& data)

Modified: trunk/glib/src/checksum.hg
==============================================================================
--- trunk/glib/src/checksum.hg	(original)
+++ trunk/glib/src/checksum.hg	Sun Jan 20 18:16:54 2008
@@ -29,9 +29,20 @@
 namespace Glib
 {
 
+/** Computes the checksum for data.
+ * This is a generic API for computing checksums (or "digests") for a sequence of arbitrary bytes, 
+ * using various hashing algorithms like MD5, SHA-1 and SHA-256. Checksums are commonly used in various environments and specifications.
+ *
+ * glibmm supports incremental checksums by calling g_checksum_update() as long as there's data available and then using get_string() 
+ * or get_digest() to compute the checksum and return it either as a string in hexadecimal form, or as a raw sequence of bytes. 
+ * To compute the checksum for binary blobs and NULL-terminated strings in one go, use the static compute_checksum() convenience functions().
+ *
+ * @newin2p16
+ */
 class Checksum
 {
   _CLASS_OPAQUE_COPYABLE(Checksum, GChecksum, NONE, g_checksum_copy, g_checksum_free)
+  _IGNORE(g_checksum_copy, g_checksum_free)
 public:
 
   /**
@@ -52,14 +63,17 @@
 
 #m4 _CONVERSION(`ChecksumType', `GChecksumType', `(($2)$3)')
 
-  /**
-   * Create a checksum object for a given checksum type.
+  /** Creates a new Checksum, using the checksum algorithm @a checksum_type. 
+   * If the checksum_type is not known, then operator bool() will return false.
    *
    * @param type checksum type, one of defined above.
-   *
-   * @return new checksum object.
    */
-  Checksum(ChecksumType checksum_type);
+  explicit Checksum(ChecksumType checksum_type);
+
+  /** Returns true if the Checksum object is valid.
+   * This will return false, for instance, if an unsupported checksum type was provided to the constructor.
+   */
+  operator bool() const;
   
   _WRAP_METHOD(void update(const guchar* data, gsize length), g_checksum_update)
 
@@ -82,16 +96,18 @@
    * @param checksum_type A ChecksumType
    * @param str The string to compute the checksum of.
    * @result The checksum as a hexadecimal string.
-   *
-   * @newin2p16
    */
   static std::string compute_checksum(ChecksumType type, const std::string& str);
   _IGNORE(g_compute_checksum_for_string)
 
-  /* TODO: Can not use _WRAP_METHOD because for some reason it takes ChecksumType
-   * as pointer, treating it as object. This problem is related to code
-   * generated from h2def, where def treat ChecksumType as object */
-  static gssize get_length(ChecksumType type);
+
+  //We don't use _WRAP_METHOD because this is not really a GCheckSum function:
+  /** Gets the length in bytes of digests of type @a checksum_type.
+   *
+   * @param checksum_type A ChecksumType.
+   * @result The checksum length, or -1 if @a checksum_type is not supported.
+   */
+  static gssize get_length(ChecksumType checksum_type);
 };
 
 } //namespace Glib