functions.inc: Exceptions instead of setLastError(); small documentation changes

diff --git a/inc/functions.inc b/inc/functions.inc
index 78e3690..bf85b36 100644 (file)
--- a/inc/functions.inc
+++ b/inc/functions.inc
@@ -96,17 +96,17 @@ function isAct($strAct) {
 }
 
 /**
- * Get the real user name for an account name
+ * Get the real user name for an account name. If the function fails, it throws
+ * an Exception.
  * @param $strAct (string) Account name of the user to look up
- * @return (string) The real name of the user. If the function fails, it returns <tt>null</tt>.
- *  Call getLastError() to get more information about the error.
+ * @return (string) The real name of the user. 
+ * @throws Exception
  */
 function getRealUserName($strAct) {
-  $hQuery = db_query("SELECT firstname, lastname FROM users WHERE act = $1;", $strAct);
+  $hQuery = db_query("SELECT firstname, lastname FROM users WHERE act = $1;",
+    $strAct);
   if(!is_resource($hQuery)) {
-    // TODO throw exception
-    setLastError(RS_ERROR_SQL);
-    return null;
+    throw new Exception(RS_ERROR_SQL);
   }
   if(pg_num_rows($hQuery) == 0) {
     return $strAct;     // User not found in database, return account name
@@ -116,33 +116,29 @@ function getRealUserName($strAct) {
 }
 
 /**
- * Determine if a specified group exists
+ * Determine if a specified group exists. If the function fails, it throws an 
+ * Exception.
  * @param $strAct (string) Account name of the group
- * @return  (bool / null) If the function fails, it returns <tt>null</tt>. Call getLastError() to
- *  get more information about the error.
+ * @return bool
+ * @throws Exception
  */
 function isGroup($strAct) {
   $hQuery = db_query("SELECT * FROM groups WHERE act = $1;", $strAct);
   if(!is_resource($hQuery)) {
-    // TODO throw exception
-    setLastError(RS_ERROR_SQL);
-    return null;
+    throw new Exception(RS_ERROR_SQL);
   }
   return (pg_num_rows($hQuery) > 0);
 }
 
 /**
- * Look up the name of a group
+ * Look up the name of a group. If the function fails, it throws an Exception.
  * @param $strAct (string) Account name of the group
- * @return (string) The name of the group. If the function fails, it returns <tt>null</tt>.
- *  Call getLastError() to get more information about the error.
+ * @return (string) The name of the group.
  */
 function getGroupName($strAct) {
   $hQuery = db_query("SELECT * FROM groups WHERE act = $1;", $strAct);
   if(!is_resource($hQuery)) {
-    // TODO throw exception
-    setLastError(RS_ERROR_SQL);
-    return null;
+    throw new Exception(RS_ERROR_SQL);
   }
   if(pg_num_rows($hQuery) == 0) {
     return $strAct;     // Group not found in database, return account name
@@ -152,9 +148,8 @@ function getGroupName($strAct) {
 }
 
 /**
- * Create a link to write a mail to the specified account name.
- * This function returns a link if the specified account exists, otherwise it returns the
- * account name.
+ * Create a link to write a mail to the specified account name. Returns a link 
+ * if the specified account exists, otherwise it returns the account name.
  * @param $strAct (string) Account name
  * @param $strColor (string) Background color for icon()
  * @param $strParams (string) additional URL parameters
@@ -175,13 +170,13 @@ function mailToUserLink($strAct, $strColor = "bl", $strParams = "") {
  * @return string
  */
 function isMailAddress($strAddr) {
-  return ((preg_match("/([a-zA-Z0-9_\-\.]*(@[a-zA-Z0-9\-\.]*)?(\s*,\s*)?)+/", $strAddr) > 0)
-  and (preg_match("/(\s*,\s*)$/", $strAddr) == 0));
+  return ((preg_match("/([a-zA-Z0-9_\-\.]*(@[a-zA-Z0-9\-\.]*)?(\s*,\s*)?)+/",
+    $strAddr) > 0) && (preg_match("/(\s*,\s*)$/", $strAddr) == 0));
 }
 
 /**
- * Module-specific logging function.
- * Prefixes the log message with a module-specific string and writes it to the logs.
+ * Module-specific logging function. Prefixes the log message with a 
+ * module-specific string and writes it to the logs.
  * @param $strLog (string) Log message
  * @return void
  */