Add information on saturating and improve example

Author: BioTurboNick

README.md

@@ -1,18 +1,18 @@
 # OverflowContexts.jl
 
 This package conceptually extends `CheckedArithmetic.jl` to provide the following overall features:
-1. Ability to set a Module-level default to overflow-checked or overflow-permissive operations.
-2. Ability to specify whether a block of code should use overflow-checked or overflow-permissive operations regardless of the default.
+1. Ability to set a Module-level default to overflow-checked, overflow-permissive (unchecked), or saturating operations.
+2. Ability to specify whether a block of code should use overflow-checked, overflow-permissive (unchecked), or saturating operations regardless of the default.
 
 Together, these provide checked and unchecked contexts, as in other languages like C#:
 https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/checked-and-unchecked
 
-The expression-level `@checked` and `@unchecked` rewrite instances of `+`, `-`, `*`, `^`, and `abs` functions, to functions specific to the
+The expression-level `@checked`, `@unchecked`, and `@saturating` rewrite instances of `+`, `-`, `*`, `^`, and `abs` functions, to functions specific to the
 checked or permissive operation, and thus are not affected by switching the default. Symbols for the functions will also be replaced, to support
 calls like `foldl(+, v)`. If these macros are nested, the lowest level takes precedence so that an unchecked context can be nested inside a checked
 context and vice versa.
 
-`@default_checked` and `@default_unchecked` create shadow copies of the `+`, `-`, `*`, `^`, and `abs` functions that redirect to overflow-checked
+`@default_checked`, `@default_unchecked`, and `@default_saturating` create shadow copies of the `+`, `-`, `*`, `^`, and `abs` functions that redirect to overflow-checked
 or overflow-permissive operations, respectively, within the module it was executed in. All arguments that don't support overflow checking are passed
 through to their respective Base methods. **Important:** If you wish to use this feature, the first usage of this macro must occur earlier than the first usage of the affected Base functions. It should only be set once per module, though switching is allowed for interactive use. It is not necessary to set a default to use the expression-level macros.
 
@@ -41,7 +41,7 @@ d() = x + 1; c() = d(); b() = c(); a() = b();
 a() #-9223372036854775808
 @checked a() # doesn't cross function boundary; no OverflowError
 
-@default_checked
+@default_checked # previous uses of operator in this module recompiled with new default
 a() # ERROR: OverflowError: 9223372036854775807 + 1 overflowed for type Int64
 
 @unchecked a() # doesn't cross function boundary; still throws OverflowError
@@ -53,8 +53,8 @@ a()  # -9223372036854775808
 @checked foldl(+, (typemax(Int), 1))
 
 # assignment operators
-a = typemax(Int)
-@checked a += 1 # OverflowError: 9223372036854775807 + 1 overflowed for type Int64
+aa = typemax(Int)
+@checked aa += 1 # OverflowError: 9223372036854775807 + 1 overflowed for type Int64
 ```
 
 If you are implementing your own numeric types, this package should just work for you so long as you extend the Base operators and the Base.Checked `checked_` methods.