cachematrix.R

# Implmentation of a special matrix object which is able to cache the inverse of the 
# matrix. If the inverse will be taken from the (previously determined and) cached result 
# or has been calculated on the fly is transparent to the user.
#
# In order to use the framework, you have to do the following:
#	1. You need to create a wrapped version of your regular matrix, e.g.
#		m <- makeCacheMatrix (matrix (c(2,1,3,2), 2, 2))
#
#	2. To retrieve the enclosed matrix use
#		m$get()
#
#	3. To replace the enclosed matrix use e.g.
#		m$set (matrix (m$get() + 1)
#
#	4. To retrieve the inverse of the matrix use
#		cacheSolve(m)


makeCacheMatrix <- function(x = matrix()) {
# Special version of a Matrix object wich is capable to cache the inverse of the matrax
#
# Args:
#   x: A regular / square matrix, which has to be invertible
#
# Returns:
#   Returns a special matrix object of the matrix 'x' which has the capability to cache the inverse 
#   of 'x'. In fact what we return is a list of four functions in order to access the matrix and it's
#	inverse version:
#		set = function(x): used to set the matrix 'x' and invalidate the cache
#		get = function(): used to return the stored matrix
#		setInv = function(inv): used to store the (external calculated) inverse matrix 'inv' in the cache
#		getInv = function(): used to get the prior cached inverse matrix. Returns 'NULL' if the cache
#			is currently empty.

	# mark the cache as being empty
	cache <- NULL
	
	# setter function to set the new matrix and to invalidate the cache
	setMatrix <- function(y) {
		x <<- y
		cache <<- NULL
	}
	
	# getter function in order to get the embedded matrix
	getMatrix <- function() x
	
	# setter function to store the inverse of the matrix in the cache
	cache <- function(inv) cache <<- inv
	
	# getter function to retrive the cached value
	uncache <- function() cache
	
	# build the wrapper object and return is
	list (set=setMatrix, get=getMatrix, setInv=cache, getInv=uncache)
}


cacheSolve <- function(x, ...) {
# Return a matrix that is the inverse of 'x'. If the same object 'x' has been used before 
# by this functions, the cached version of the inverse of 'x' is returned instead.
# Otherwiese the inverse of 'x' is being calculated, return and is stored in the local cache.
#
# Args:
#	x: Cahced version of a regular / square matrix, generated by 'makeCacheMatrix'
#	...: anny additional arguments which are being passed directly to the R solve function.
#
# Returns:
#	The inverse of the matrix encapsulated by 'x'.

	# Let's see if we have a cached value
	inv <- x$getInv()
	if (!is.null(inv)) {
		message ("getting inverse matrix from cache")
		return (inv)
	}
	
	# Nothing in cache so far, need to calculate the inverse of the matrix now.
	inv <- solve (x$get())
	
	# store calculated inverse of the matrix in the cache
	x$setInv(inv)
	
	# return the inverse matrix itself
	inv
}