From 5a7898a59360a555065494afd1fb8e6912bf3902 Mon Sep 17 00:00:00 2001
From: Rick Coates <rick@jacketscreative.com>
Date: Mon, 21 Apr 2014 09:44:02 -0300
Subject: [PATCH] Implemented the programming assignment to create a pair of
 functions that cache the inverse of a matrix.

---
 cachematrix.R | 76 +++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 67 insertions(+), 9 deletions(-)

diff --git a/cachematrix.R b/cachematrix.R
index a50be65aa44..cd6b1589eb9 100644
--- a/cachematrix.R
+++ b/cachematrix.R
@@ -1,15 +1,73 @@
-## Put comments here that give an overall description of what your
-## functions do
-
-## Write a short comment describing this function
+## The following pair of functions implement a special matrix that can cache
+## its own inverse. 
+##
+## makeCacheMatrix creates the special matrix, which is actually a list of
+## functions that can get/set the matrix and get/set the inverse of the matrix.
+##
+## cacheSolve computes the inverse of a special matrix created by makeCacheMatrix.
+## If the inverse of the matrix has already been computed, it returns the 
+## cached copy of the inverse.
 
 makeCacheMatrix <- function(x = matrix()) {
-
+  # Creates a list of getter/setter functions for both the matrix and its 
+  # inverse. This function could be thought of as a "factory" for special 
+  # matrices that can cache their inverse.
+  #
+  # Args: 
+  #   x: The matrix for which the special (inverse caching) matrix is to 
+  #      be created.
+  #
+  # Returns:
+  #   A list of functions: set: sets the value of the matrix
+  #                        get: returns the value of the matrix
+  #                        setinverse: sets the inverse of the matrix
+  #                        getinverse: returns the inverse of the matrix
+  #                        
+  if (!is.matrix(x)) { # error handling
+    stop("x must be a matrix")
+  }
+  inv <- NULL # initalize the inverse
+  # define the matrix setter function
+  set <- function(y) {
+    if (!is.matrix(y)) { # error handling
+      stop("The argument for set must be a matrix.")
+    }
+    x   <<- y
+    inv <<- NULL # re-initialize the inverse
+  }  
+  # define the matrix getter function
+  get <- function() x
+  # define the inverse setter function
+  setinverse <- function(inverse) inv <<- inverse
+  # define the inverse getter function
+  getinverse <- function() inv
+  # create and return the list of functions that comprise the special matrix
+  list(set = set, get = get,
+       setinverse = setinverse,
+       getinverse = getinverse) 
 }
 
-
-## Write a short comment describing this function
-
 cacheSolve <- function(x, ...) {
-        ## Return a matrix that is the inverse of 'x'
+  # Returns a matrix that is the inverse of the special matrix 'x'. If x already
+  # contains a cached copy of its inverse, the cached copy is returned. Otherwise, 
+  # the inverse is computed and cached before it is returned.
+  #
+  # Args:
+  #   x: The special matrix for which the inverse is desired. The matrix must
+  #      be a square invertible matrix.
+  #
+  # Returns:
+  #   A matrix that is the inverse of x.
+  inv <- x$getinverse()
+  # if the special matrix already contains its inverse, return the cached copy
+  if(!is.null(inv)) {
+    message("getting cached inverse...")
+    return(inv)
+  }
+  # otherwise, compute the inverse
+  inv <- solve(x$get())
+  # cache the result, so subsequent calls do not need to recompute the inverse
+  x$setinverse(inv)
+  # and return the resulting inverse
+  inv
 }