README and playground updates

Author: dingosky

EntropyString.playground/Pages/Character Sets.xcplaygroundpage/Contents.swift

@@ -1,19 +1,15 @@
 //: [Previous](@previous)
 //: ## Character Sets
 //:
-//: As we've seen in the previous sections, `EntropyString` provides default characters for each of
-//: the supported character sets. Let's see what's under the hood.
-import EntropyString
+//: As we\'ve seen in the previous sections, `EntropyString` provides default characters for each of the supported character sets. Let\'s see what\'s under the hood. The available `CharSet`s are *.charSet64*, *.charSet32*, *.charSet16*, *.charSet8*, *.charSet4* and *.charSet2*. The default characters for each were chosen as follows:
+  import EntropyString
 
-print("Base 64: \(RandomString.characters(for: .charSet64))\n")
-//: The call to `RandomString.characters(for:)` returns the characters used for any of the
-//: character sets defined by the `RandomString.CharBase enum`. The following code reveals all the
-//: character sets.
-print("Base 32: \(RandomString.characters(for: .charSet32))\n")
-print("Base 16: \(RandomString.characters(for: .charSet16))\n")
-print("Base  8: \(RandomString.characters(for: .charSet8))\n")
-print("Base  4: \(RandomString.characters(for: .charSet4))\n")
-print("Base  2: \(RandomString.characters(for: .charSet2))\n")
+  print("Base 64 chars: \(CharSet.charSet64.chars)\n")
+  print("Base 32 chars: \(CharSet.charSet32.chars)\n")
+  print("Base 16 chars: \(CharSet.charSet16.chars)\n")
+  print("Base  8 chars: \(CharSet.charSet8.chars)\n")
+  print("Base  4 chars: \(CharSet.charSet4.chars)\n")
+  print("Base  2 chars: \(CharSet.charSet2.chars)\n")
 //: The default character sets were chosen as follows:
 //:  - Base 64: **ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_**
 //:     - The file system and URL safe char set from
@@ -33,7 +29,6 @@ print("Base  2: \(RandomString.characters(for: .charSet2))\n")
 //:  - Base  2: **01**
 //:     - Binary
 //:
-//: You may, of course, want to choose the characters used, which is covered next in [Custom
-//: Characters](Custom%20Characters).
+//: You may, of course, want to choose the characters used, which is covered next in [Custom Characters](Custom%20Characters).
 //:
 //: [TOC](Table%20of%20Contents) | [Next](@next)

EntropyString.playground/Pages/Custom Bytes.xcplaygroundpage/Contents.swift

@@ -1,37 +1,27 @@
 //: [Previous](@previous)
 //: ## Custom Bytes
 //:
-//: As described in [Secure Bytes](Secure%20Bytes), `EntropyString` automatically generates random
-//: bytes using either `SecRandomCopyBuf` or `arc4random_buf`. These functions are fine, but you
-//: may have a need to provide your own btyes, say for deterministic testing or to use a
-//: specialized byte genterator. The `RandomString.entropy(of:using:bytes)` function allows 
-//: passing in your own bytes to create a string.
+//: As described in [Secure Bytes](Secure%20Bytes), `EntropyString` automatically generates random bytes using either `SecRandomCopyBuf` or `arc4random_buf`. These functions are fine, but you may have a need to provide your own btyes for deterministic testing or to use a specialized byte genterator. The function `random.string(bits:using)` allows specifying your own bytes to create a string.
 //:
-//: Suppose we want a string capable of 30 bits of entropy using 32 characters. We pass in 4 bytes
-//: (to cover the 30 bits):
-import EntropyString
+//: Suppose we want a string capable of 30 bits of entropy using 32 characters. We pass in 4 bytes (to cover the 30 bits):
+  import EntropyString
 
-let bytes: RandomString.Bytes = [250, 200, 150, 100]
-let string = try! RandomString.entropy(of: 30, using: .charSet32, bytes: bytes)
-print("String: \(string)\n")
+  let random = Random()
+  let bytes: [UInt8] = [250, 200, 150, 100]
+  let string = try! random.string(bits: 30, using: bytes)
+
+  print("String: \(string)\n")
 //: * callout(string): Th7fjL
 //:
-//: The __bytes__ provided can come from any source. However, the number of bytes must be
-//: sufficient to generate the string as described in the [Efficiency](Efficiency) section.
-//: `RandomString.entropy(of:using:bytes)` throws `RandomString.RandomError.tooFewBytes` if
-//: the string cannot be formed from the passed bytes.
-do {
-  try RandomString.entropy(of: 32, using: .charSet32, bytes: bytes)
-}
-catch {
-  print(error)
-}
+//: The __bytes__ provided can come from any source. However, if the number of bytes is insufficient to generate the string as described in the [Efficiency](Efficiency) section, an `EntropyStringError.tooFewBytes` is thrown.
+  do {
+    try random.string(bits: 32, using: bytes)
+  }
+  catch {
+    print(error)
+  }
 //: * callout(error): tooFewBytes
 //:
-//: Note how the number of bytes needed is dependent on the number of characters in our set.
-//: In using a string to represent entropy, we can only have multiples of the bits of entropy per
-//: character used. So in the example above, to get at least 32 bits of entropy using a character
-//: set of 32 characters (5 bits per char), we'll need enough bytes to cover 35 bits, not 32, so
-//: a `tooFewBytes` error is thrown.
+//: Note the number of bytes needed is dependent on the number of characters in our set. In using a string to represent entropy, we can only have multiples of the bits of entropy per character used. So in the example above, to get at least 32 bits of entropy using a character set of 32 characters (5 bits per char), we'll need enough bytes to cover 35 bits, not 32, so a `tooFewBytes` error is thrown.
 //:
-//: [TOC](Table%20of%20Contents)
+//: [TOC](Table%20of%20Contents) | [Next](@next)

EntropyString.playground/Pages/Custom Characters.xcplaygroundpage/Contents.swift

@@ -1,57 +1,49 @@
 //: [Previous](@previous)
 //: ## Custom Characters
 //:
-//: Being able to easily generate random strings is great, but what if you want to specify your
-//: own characters? For example, suppose you want to visualize flipping a coin to produce 10 bits
-//: of entropy.
-import EntropyString
+//: Being able to easily generate random strings is great, but what if you want to specify your own characters? For example, suppose you want to visualize flipping a coin to produce 10 bits of entropy.
+  import EntropyString
 
-let randomString = RandomString()
-var flips = randomString.entropy(of: 10, using: .charSet2)
-print("flips: \(flips)\n")
+  let random = Random(.charSet2)
+  var flips = random.string(bits: 10)
+
+  print("flips: \(flips)\n")
 //: * callout(flips): 0101001110
 //:
-//: The resulting string of __0__'s and __1__'s doesn't look quite right. You want to use the
-//: characters __H__ and __T__ instead.
-try! randomString.use("HT", for: .charSet2)
-flips = randomString.entropy(of: 10, using: .charSet2)
-print("flips: \(flips)\n")
+//: The resulting string of __0__'s and __1__'s doesn't look quite right. Perhaps you want to use the characters __H__ and __T__ instead.
+  try! random.use("HT")
+  flips = random.string(bits: 10)
+
+  print("flips: \(flips)\n")
 //: * callout(flips): HTTTHHTTHH
 //:
-//: Note that setting custom characters in the above code requires using an *instance* of
-//: `RandomString`, wheras in the previous sections we used *class* functions for all calls. The
-//: function signatures are the same in each case, but you can't change the static character sets
-//: used in the class `RandomString` (i.e., there is no `RandomString.use(_,for:)` function).
-//:
-//: As another example, we saw in [Character Sets](Character%20Sets) the default characters for
-//: charSet 16 are **0123456789abcdef**. Suppose you like uppercase hexadecimal letters instead.
-try! randomString.use("0123456789ABCDEF", for: .charSet16)
-let hex = randomString.entropy(of: 48, using: .charSet16)
-print("hex: \(hex)\n")
+//: As another example, we saw in [Character Sets](Character%20Sets) the default characters for `charSet16` are **0123456789abcdef**. Suppose you like uppercase hexadecimal letters instead.
+  try! random.use("0123456789ABCDEF")
+  let hex = random.string(bits: 48)
+
+  print("hex: \(hex)\n")
 //: * callout(hex): 4D20D9AA862C
 //:
-//: Or suppose you want a random password with numbers, lowercase letters and special characters.
-try! randomString.use("1234567890abcdefghijklmnopqrstuvwxyz-=[];,./~!@#$%^&*()_+{}|:<>?", for: .charSet64)
-let password = randomString.entropy(of: 64, using: .charSet64)
-print("password: \(password)")
-//: * callout(password): }4?0x*$o_=w
-//:
-//: Note that `randomString.use(_,for:)` throws a `RandomStringError` if the number of characters
-//: doesn't match the number required for the character set or if the characters are not unique.
-do {
-  try randomString.use("abcdefg", for: .charSet8)
-}
-catch {
-  print(error)
-}
+//: The `Random` constructor allows for three separate cases:
+//:   - No argument defauls to the `charSet32` characters.
+//:   - One of six default `CharSet`s can be specified.
+//:   - A string representing the characters to use can be specified.
+//:
+//: The 3rd option above will throw an `EntropyStringError` if the characters string isn't appropriate for creating a `CharSet`.
+  do {
+    try random.use("abcdefg")
+  }
+  catch {
+    print(error)
+  }
 //: * callout(error): invalidCharCount
 //:
-do {
-  try randomString.use("01233210", for: .charSet8)
-}
-catch {
-  print(error)
-}
+  do {
+    try random.use("01233210")
+  }
+  catch {
+    print(error)
+  }
 //: * callout(error): charsNotUnique
 //:
 //: [TOC](Table%20of%20Contents) | [Next](@next)

EntropyString.playground/Pages/Efficiency.xcplaygroundpage/Contents.swift

@@ -1,24 +1,11 @@
 //: [Previous](@previous)
 //: ## Efficiency
 //:
-//: To efficiently create random strings, `EntropyString` generates the necessary number of
-//: bytes needed for each the string and uses those bytes in a bit shifting scheme to index into
-//: a character set. For example, consider generating strings from the `.charSet32` character
-//: set. There are __32__ characters in the set, so an index into an array of those characters
-//: would be in the range `[0,31]`. Generating a random string of `.charSet32` characters is thus
-//: reduced to generating a random sequence of indices in the range `[0,31]`.
-//:
-//: To generate the indices, `EntropyString` slices just enough bits from the array of bytes to create
-//: each index. In the example at hand, 5 bits are needed to create an index in the range
-//: `[0,31]`. `EntropyString` processes the byte array 5 bits at a time to create the indices. The first
-//: index comes from the first 5 bits of the first byte, the second index comes from the last 3 bits of
-//: the first byte combined with the first 2 bits of the second byte, and so on as the byte array is
-//: systematically sliced to form indices into the character set. And since bit shifting and addition
-//: of byte values is really efficient, this scheme is quite fast.
-//:
-//: The `EntropyString` scheme is also efficient with regard to the amount of randomness used. Consider
-//: the following common Swift solution to generating random strings. To generated a character, an index
-//: into the available characters is create using `arc4random_uniform`. The code looks something like:
+//: To efficiently create random strings, `EntropyString` generates the necessary number of bytes needed for each the string and uses those bytes in a bit shifting scheme to index into a character set. For example, consider generating strings from the *charSet32* character set. There are __32__ characters in the set, so an index into an array of those characters would be in the range `[0,31]`. Generating a random string of *charSet32* characters is thus reduced to generating a random sequence of indices in the range `[0,31]`.
+//:
+//: To generate the indices, `EntropyString` slices just enough bits from the array of bytes to create each index. In the example at hand, 5 bits are needed to create an index in the range `[0,31]`. `EntropyString` processes the byte array 5 bits at a time to create the indices. The first index comes from the first 5 bits of the first byte, the second index comes from the last 3 bits of the first byte combined with the first 2 bits of the second byte, and so on as the byte array is systematically sliced to form indices into the character set. And since bit shifting and addition of byte values is really efficient, this scheme is quite fast.
+//:
+//: The `EntropyString` scheme is also efficient with regard to the amount of randomness used. Consider the following common Swift solution to generating random strings. To generated a character, an index into the available characters is create using `arc4random_uniform`. The code looks something like:
 //:
 //:    for _ in 0 ..< len {
 //:      let offset = Int(arc4random_uniform(charCount))
@@ -27,22 +14,11 @@
 //:      string += String(char)
 //:    }
 //:
-//: In the code above, `arc4random_uniform` generates 32 bits of randomness, returned as an `UInt32`. The
-//: returned value is used to create an **index**. Suppose we're creating strings with **len=16** and
-//: **charCount=32**. Each **char** consumes 32 bits of randomness (`UInt32`) while only injecting 5 bits
-//: (`log2(32)`) of entropy into **string**. The resulting string has an information carrying capacity of
-//: 80 bits. So creating each **string** requires a *total* of 512 bits of randomness while only actually
-//: *carrying* 80 bits of that entropy forward in the string itself. That means 432 bits (84% of the total!)
-//: of the generated randomness is simply wasted.
-//:
-//: Compare that to the `EntropyString` scheme. For the example above, slicing off 5 bits at a time
-//: requires a total of 80 bits (10 bytes). Creating the same strings as above, `EntropyString` uses 80
-//: bits of randomness per string with no wasted bits. In general, the `EntropyString` scheme can waste
-//: up to 7 bits per string, but that's the worst case scenario and that's *per string*, not *per
-//: character*!
-//:
-//: Fortunately you don't need to really understand how the bytes are efficiently sliced and diced to get
-//: the string. But you may want to know that [Secure Bytes](#SecureBytes) are used, and that's the next
+//: In the code above, `arc4random_uniform` generates 32 bits of randomness, returned as an `UInt32`. The returned value is used to create **index**. Suppose we're creating strings with **len=16** and **charCount=32**. Each **char** consumes 32 bits of randomness (`UInt32`) while only injecting 5 bits (`log2(32)`) of entropy into **string**. The resulting string has an information carrying capacity of 80 bits. So creating each string requires a *total* of 512 bits of randomness while only actually *carrying* 80 bits of that entropy forward in the string itself. That means 432 bits (84% of the total!) of the generated randomness is simply wasted.
+//:
+//: Compare that to the `EntropyString` scheme. For the example above, slicing off 5 bits at a time requires a total of 80 bits (10 bytes). Creating the same strings as above, `EntropyString` uses 80 bits of randomness per string with no wasted bits. In general, the `EntropyString` scheme can waste up to 7 bits per string, but that's the worst case scenario and that's *per string*, not *per character*!
+//:
+//: Fortunately you don't need to really understand how the bytes are efficiently sliced and diced to get the string. But you may want to know that [Secure Bytes](#SecureBytes) are used, and that's the next
 //: topic.
 //:
 //: [TOC](Table%20of%20Contents) | [Next](@next)