Add raise vs E2MM

- Add descriptopn of Exception2MessageMapper

Closes #51

Author: sshaw

README.md

@@ -102,6 +102,45 @@ Comparison:
 module_eval with string:     1129.7 i/s - 1.19x slower
 ```
 
+##### `raise` vs `E2MM#Raise` for raising (and defining) exeptions  [code](code/general/raise-vs-e2mmap.rb)
+
+Ruby's [Exception2MessageMapper module](http://ruby-doc.org/stdlib-2.2.0/libdoc/e2mmap/rdoc/index.html) allows one to define and raise exceptions with predefined messages.
+
+```
+$ ruby -v code/general/raise-vs-e2mmap.rb
+ruby 2.2.3p173 (2015-08-18 revision 51636) [x86_64-darwin14]
+
+Calculating -------------------------------------
+Ruby exception: E2MM#Raise
+                         2.865k i/100ms
+Ruby exception: Kernel#raise
+                        42.215k i/100ms
+-------------------------------------------------
+Ruby exception: E2MM#Raise
+                         27.270k (± 8.8%) i/s -    137.520k
+Ruby exception: Kernel#raise
+                        617.446k (± 7.9%) i/s -      3.082M
+
+Comparison:
+Ruby exception: Kernel#raise:   617446.2 i/s
+Ruby exception: E2MM#Raise:    27269.8 i/s - 22.64x slower
+
+Calculating -------------------------------------
+Custom exception: E2MM#Raise
+                         2.807k i/100ms
+Custom exception: Kernel#raise
+                        45.313k i/100ms
+-------------------------------------------------
+Custom exception: E2MM#Raise
+                         29.005k (± 7.2%) i/s -    145.964k
+Custom exception: Kernel#raise
+                        589.149k (± 7.8%) i/s -      2.945M
+
+Comparison:
+Custom exception: Kernel#raise:   589148.7 i/s
+Custom exception: E2MM#Raise:    29004.8 i/s - 20.31x slower
+```
+
 #### Method Invocation
 
 ##### `call` vs `send` vs `method_missing` [code](code/method/call-vs-send-vs-method_missing.rb)
@@ -163,6 +202,9 @@ Comparison:
 Function with single Array argument:  5580972.6 i/s
 Function with splat arguments:    54427.7 i/s - 102.54x slower
 
+Ruby's [Exception2MessageMapper module](http://ruby-doc.org/stdlib-2.2.0/libdoc/e2mmap/rdoc/index.html)
+allows one to define and raise exceptions with predefined messages.
+
 ```
 
 ### Array

code/general/raise-vs-e2mmap.rb

@@ -0,0 +1,73 @@
+require 'benchmark/ips'
+require 'e2mmap'
+
+class WithE2MM
+  extend Exception2MessageMapper
+
+  def_e2message TypeError, 'argument must be a %s'
+  def_exception :FooError, 'foo: %s'
+
+  def self.raise_ruby_defined
+    Raise TypeError, 'Hash'
+  end
+
+  def self.raise_user_defined
+    Raise FooError, 'bar!'
+  end
+end
+
+class WithoutE2MM
+  FooError = Class.new(StandardError)
+
+  def self.raise_ruby_defined
+    raise TypeError, 'argument must be a Hash'
+  end
+
+  def self.raise_user_defined
+    raise FooError, 'foo: bar!'
+  end
+end
+
+def slow_ruby_defined
+  begin
+    WithE2MM.raise_ruby_defined
+  rescue
+    'fast ruby'
+  end
+end
+
+def fast_ruby_defined
+  begin
+    WithoutE2MM.raise_ruby_defined
+  rescue
+    'fast ruby'
+  end
+end
+
+def slow_user_defined
+  begin
+    WithE2MM.raise_user_defined
+  rescue
+    'fast ruby'
+  end
+end
+
+def fast_user_defined
+  begin
+    WithoutE2MM.raise_user_defined
+  rescue
+    'fast ruby'
+  end
+end
+
+Benchmark.ips do |x|
+  x.report('Ruby exception: E2MM#Raise')   { slow_ruby_defined }
+  x.report('Ruby exception: Kernel#raise') { fast_ruby_defined }
+  x.compare!
+end
+
+Benchmark.ips do |x|
+  x.report('Custom exception: E2MM#Raise')   { slow_user_defined }
+  x.report('Custom exception: Kernel#raise') { fast_user_defined }
+  x.compare!
+end