* mu-msg-iter.{cc,h}: some cleanups, documentation updates

src/mu-msg-iter.cc

@@ -21,7 +21,7 @@
 #include <iostream>
 #include <string.h>
 #include <errno.h>
-#include "xapian.h"
+#include <xapian.h>
 
 #include "mu-util.h"
 #include "mu-msg-iter.h"
@@ -88,6 +88,7 @@ mu_msg_iter_get_msg (MuMsgIter *iter)
 	MuMsg *msg;
 	
 	g_return_val_if_fail (iter, NULL);
+	g_return_val_if_fail (!mu_msg_iter_is_null(iter), NULL);
 	
 	path = mu_msg_iter_get_path (iter);
 	if (!path) {
@@ -140,7 +141,8 @@ gboolean
 mu_msg_iter_next (MuMsgIter *iter)
 {
 	g_return_val_if_fail (iter, FALSE);
-
+	g_return_val_if_fail (!mu_msg_iter_is_null(iter), FALSE);
+	
 	try {
 		++iter->_offset;
 		if (++iter->_cursor == iter->_matches.end())
@@ -172,18 +174,15 @@ mu_msg_iter_next (MuMsgIter *iter)
 gboolean
 mu_msg_iter_is_null (MuMsgIter *iter)
 {
-	g_return_val_if_fail (iter, TRUE);
-
-	return iter->_is_null;
+	return iter ? iter->_is_null : TRUE;
 }
 
 
 const gchar*
 mu_msg_iter_get_field (MuMsgIter *iter, const MuMsgField *field)
 {
-	g_return_val_if_fail (iter, NULL);
-	g_return_val_if_fail (!mu_msg_iter_is_null(iter), NULL);
 	g_return_val_if_fail (field, NULL);
+	g_return_val_if_fail (!mu_msg_iter_is_null(iter), NULL);
 	
 	try {
 		MuMsgFieldId id;
@@ -202,10 +201,12 @@ mu_msg_iter_get_field (MuMsgIter *iter, const MuMsgField *field)
 
 gint64
 mu_msg_iter_get_field_numeric (MuMsgIter *iter,
-				      const MuMsgField *field)
+			       const MuMsgField *field)
 {
+	g_return_val_if_fail (field, -1);
+	g_return_val_if_fail (!mu_msg_iter_is_null(iter), -1);
 	g_return_val_if_fail (mu_msg_field_is_numeric(field), -1);
-
+	
 	try {
 		return static_cast<gint64>(
 			Xapian::sortable_unserialise(
@@ -235,8 +236,7 @@ get_field_number (MuMsgIter *iter, MuMsgFieldId id)
 unsigned int
 mu_msg_iter_get_docid (MuMsgIter *iter)
 {
-	g_return_val_if_fail (iter, 0);
-
+	g_return_val_if_fail (!mu_msg_iter_is_null(iter), -1);	
 	try {
 		return iter->_cursor.get_document().get_docid();
 
@@ -247,6 +247,7 @@ mu_msg_iter_get_docid (MuMsgIter *iter)
 const char*
 mu_msg_iter_get_path (MuMsgIter *iter)
 {
+	g_return_val_if_fail (!mu_msg_iter_is_null(iter), NULL);
 	return get_field (iter, MU_MSG_FIELD_ID_PATH);
 }
 
@@ -254,12 +255,14 @@ mu_msg_iter_get_path (MuMsgIter *iter)
 const char*
 mu_msg_iter_get_from (MuMsgIter *iter)
 {
+	g_return_val_if_fail (!mu_msg_iter_is_null(iter), NULL);
 	return get_field (iter, MU_MSG_FIELD_ID_FROM);
 }
 
 const char*
 mu_msg_iter_get_to (MuMsgIter *iter)
 {
+	g_return_val_if_fail (!mu_msg_iter_is_null(iter), NULL);
 	return get_field (iter, MU_MSG_FIELD_ID_TO);
 }
 
@@ -267,6 +270,7 @@ mu_msg_iter_get_to (MuMsgIter *iter)
 const char*
 mu_msg_iter_get_cc (MuMsgIter *iter)
 {
+	g_return_val_if_fail (!mu_msg_iter_is_null(iter), NULL);
 	return get_field (iter, MU_MSG_FIELD_ID_CC);
 }
 
@@ -274,6 +278,7 @@ mu_msg_iter_get_cc (MuMsgIter *iter)
 const char*
 mu_msg_iter_get_subject (MuMsgIter *iter)
 {
+	g_return_val_if_fail (!mu_msg_iter_is_null(iter), NULL);
 	return get_field (iter, MU_MSG_FIELD_ID_SUBJECT);
 }
 
@@ -281,25 +286,30 @@ mu_msg_iter_get_subject (MuMsgIter *iter)
 size_t
 mu_msg_iter_get_size (MuMsgIter *iter)
 {
-	return (size_t) get_field_number (iter, MU_MSG_FIELD_ID_SIZE);
+	g_return_val_if_fail (!mu_msg_iter_is_null(iter), 0);
+	return static_cast<size_t>(get_field_number (iter, MU_MSG_FIELD_ID_SIZE));
 } 
 
 
 time_t
 mu_msg_iter_get_date (MuMsgIter *iter)
 {
-	return (size_t) get_field_number (iter, MU_MSG_FIELD_ID_DATE);
+	g_return_val_if_fail (!mu_msg_iter_is_null(iter), 0);
+	return static_cast<size_t> (get_field_number (iter, MU_MSG_FIELD_ID_DATE));
 } 
 
 
 MuMsgFlags
 mu_msg_iter_get_flags (MuMsgIter *iter)
 {
-	return (MuMsgFlags) get_field_number (iter, MU_MSG_FIELD_ID_FLAGS);
+	g_return_val_if_fail (!mu_msg_iter_is_null(iter), MU_MSG_FLAG_NONE);
+	return static_cast<MuMsgFlags>
+		(get_field_number (iter, MU_MSG_FIELD_ID_FLAGS));
 } 
 
 MuMsgPrio
 mu_msg_iter_get_prio (MuMsgIter *iter)
 {
-	return (MuMsgPrio) get_field_number (iter, MU_MSG_FIELD_ID_PRIO);
+	g_return_val_if_fail (!mu_msg_iter_is_null(iter), MU_MSG_PRIO_NONE);
+	return static_cast<MuMsgPrio>(get_field_number (iter, MU_MSG_FIELD_ID_PRIO));
 } 

src/mu-msg-iter.h

@@ -58,8 +58,12 @@ void		 mu_msg_iter_destroy           (MuMsgIter *iter);
 
 
 /**
- * get the corresponding MuMsg for this iter; this requires
- * the corresponding message file to be present at the expected place
+ * get the corresponding MuMsg for this iter; this requires the
+ * corresponding message file to be present at the expected place in
+ * the maildir in the file system. Note, it's faster to use the
+ * database fields (the various mu_msg_iter_get_... functions), so
+ * MuMsg should use only when information is needed that is not
+ * provided from the iter).
  * 
  * @param iter a valid MuMsgIter instance
  *