Remove Entropy

Preparing for Random -> Entropy renaming

Author: dingosky

EntropyString.xcodeproj/project.pbxproj

@@ -9,10 +9,8 @@
 /* Begin PBXBuildFile section */
 		E205C6AE1F1BFF66007C139E /* EntropyString.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = E205C6A51F1BFF66007C139E /* EntropyString.framework */; };
 		E205C6BC1F1BFFEC007C139E /* Random.swift in Sources */ = {isa = PBXBuildFile; fileRef = E287ADAD1F0E9DDC00DE6DF5 /* Random.swift */; };
-		E205C6BD1F1BFFEC007C139E /* Entropy.swift in Sources */ = {isa = PBXBuildFile; fileRef = E287ADB81F0EDCAB00DE6DF5 /* Entropy.swift */; };
 		E205C6EB1F1C02E4007C139E /* EntropyString.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = E205C6E21F1C02E3007C139E /* EntropyString.framework */; };
 		E205C6F91F1C030E007C139E /* Random.swift in Sources */ = {isa = PBXBuildFile; fileRef = E287ADAD1F0E9DDC00DE6DF5 /* Random.swift */; };
-		E205C6FA1F1C030E007C139E /* Entropy.swift in Sources */ = {isa = PBXBuildFile; fileRef = E287ADB81F0EDCAB00DE6DF5 /* Entropy.swift */; };
 		E21779C81F3E7E260019CC42 /* Bytes.swift in Sources */ = {isa = PBXBuildFile; fileRef = E21779C71F3E7E260019CC42 /* Bytes.swift */; };
 		E21779C91F3E7E260019CC42 /* Bytes.swift in Sources */ = {isa = PBXBuildFile; fileRef = E21779C71F3E7E260019CC42 /* Bytes.swift */; };
 		E21779CA1F3E7E260019CC42 /* Bytes.swift in Sources */ = {isa = PBXBuildFile; fileRef = E21779C71F3E7E260019CC42 /* Bytes.swift */; };
@@ -21,16 +19,11 @@
 		E287ADA31F0E9B9A00DE6DF5 /* EntropyString.h in Headers */ = {isa = PBXBuildFile; fileRef = E287AD951F0E9B9A00DE6DF5 /* EntropyString.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		E287ADAE1F0E9DDC00DE6DF5 /* Random.swift in Sources */ = {isa = PBXBuildFile; fileRef = E287ADAD1F0E9DDC00DE6DF5 /* Random.swift */; };
 		E287ADB51F0E9DEE00DE6DF5 /* Info.plist in Resources */ = {isa = PBXBuildFile; fileRef = E287ADB21F0E9DEE00DE6DF5 /* Info.plist */; };
-		E287ADB91F0EDCAB00DE6DF5 /* Entropy.swift in Sources */ = {isa = PBXBuildFile; fileRef = E287ADB81F0EDCAB00DE6DF5 /* Entropy.swift */; };
 		E2B8C8171F3E2B8500171502 /* CharSet.swift in Sources */ = {isa = PBXBuildFile; fileRef = E2B8C8161F3E2B8500171502 /* CharSet.swift */; };
-		E2D2DD461F436A5F006846F7 /* Entropy.swift in Sources */ = {isa = PBXBuildFile; fileRef = E287ADB81F0EDCAB00DE6DF5 /* Entropy.swift */; };
 		E2D2DD471F436AB3006846F7 /* Random.swift in Sources */ = {isa = PBXBuildFile; fileRef = E287ADAD1F0E9DDC00DE6DF5 /* Random.swift */; };
 		E2D2DD481F436AB6006846F7 /* CharSet.swift in Sources */ = {isa = PBXBuildFile; fileRef = E2B8C8161F3E2B8500171502 /* CharSet.swift */; };
 		E2D2DD491F436AB7006846F7 /* CharSet.swift in Sources */ = {isa = PBXBuildFile; fileRef = E2B8C8161F3E2B8500171502 /* CharSet.swift */; };
 		E2D2DD4A1F436AB8006846F7 /* CharSet.swift in Sources */ = {isa = PBXBuildFile; fileRef = E2B8C8161F3E2B8500171502 /* CharSet.swift */; };
-		E2E1404F1F422C70003E02B0 /* EntropyTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E2E1404E1F422C70003E02B0 /* EntropyTests.swift */; };
-		E2E140501F422C70003E02B0 /* EntropyTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E2E1404E1F422C70003E02B0 /* EntropyTests.swift */; };
-		E2E140511F422C70003E02B0 /* EntropyTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E2E1404E1F422C70003E02B0 /* EntropyTests.swift */; };
 		E2E140531F422FB1003E02B0 /* RandomTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E2E140521F422FB1003E02B0 /* RandomTests.swift */; };
 		E2E140541F422FB1003E02B0 /* RandomTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E2E140521F422FB1003E02B0 /* RandomTests.swift */; };
 		E2E140551F422FB1003E02B0 /* RandomTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E2E140521F422FB1003E02B0 /* RandomTests.swift */; };
@@ -79,11 +72,9 @@
 		E287AD9B1F0E9B9A00DE6DF5 /* EntropyString-iOSTests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = "EntropyString-iOSTests.xctest"; sourceTree = BUILT_PRODUCTS_DIR; };
 		E287ADAD1F0E9DDC00DE6DF5 /* Random.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = Random.swift; sourceTree = "<group>"; };
 		E287ADB21F0E9DEE00DE6DF5 /* Info.plist */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.plist.xml; path = Info.plist; sourceTree = "<group>"; };
-		E287ADB81F0EDCAB00DE6DF5 /* Entropy.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = Entropy.swift; sourceTree = "<group>"; };
 		E287ADBA1F0EE3B600DE6DF5 /* EntropyString.playground */ = {isa = PBXFileReference; lastKnownFileType = file.playground; path = EntropyString.playground; sourceTree = "<group>"; };
 		E2B8C8161F3E2B8500171502 /* CharSet.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CharSet.swift; sourceTree = "<group>"; };
 		E2DDF28D1F68EDD700CE76CB /* Presentation.playground */ = {isa = PBXFileReference; lastKnownFileType = file.playground; name = Presentation.playground; path = ../Presentation/Swift/Presentation.playground; sourceTree = "<group>"; };
-		E2E1404E1F422C70003E02B0 /* EntropyTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = EntropyTests.swift; sourceTree = "<group>"; };
 		E2E140521F422FB1003E02B0 /* RandomTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = RandomTests.swift; sourceTree = "<group>"; };
 		E2E140561F433A6D003E02B0 /* CharSetTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CharSetTests.swift; sourceTree = "<group>"; };
 /* End PBXFileReference section */
@@ -182,7 +173,6 @@
 		E287ADAC1F0E9DDC00DE6DF5 /* Sources */ = {
 			isa = PBXGroup;
 			children = (
-				E287ADB81F0EDCAB00DE6DF5 /* Entropy.swift */,
 				E2B8C8161F3E2B8500171502 /* CharSet.swift */,
 				E287ADAD1F0E9DDC00DE6DF5 /* Random.swift */,
 				E21779C71F3E7E260019CC42 /* Bytes.swift */,
@@ -201,7 +191,6 @@
 		E287ADB01F0E9DEE00DE6DF5 /* EntropyStringTests */ = {
 			isa = PBXGroup;
 			children = (
-				E2E1404E1F422C70003E02B0 /* EntropyTests.swift */,
 				E2E140561F433A6D003E02B0 /* CharSetTests.swift */,
 				E2E140521F422FB1003E02B0 /* RandomTests.swift */,
 				E287ADB21F0E9DEE00DE6DF5 /* Info.plist */,
@@ -498,7 +487,6 @@
 			buildActionMask = 2147483647;
 			files = (
 				E205C6BC1F1BFFEC007C139E /* Random.swift in Sources */,
-				E205C6BD1F1BFFEC007C139E /* Entropy.swift in Sources */,
 				E2D2DD481F436AB6006846F7 /* CharSet.swift in Sources */,
 				E21779C91F3E7E260019CC42 /* Bytes.swift in Sources */,
 			);
@@ -509,7 +497,6 @@
 			buildActionMask = 2147483647;
 			files = (
 				E2E140541F422FB1003E02B0 /* RandomTests.swift in Sources */,
-				E2E140501F422C70003E02B0 /* EntropyTests.swift in Sources */,
 				E2E140581F433A6D003E02B0 /* CharSetTests.swift in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
@@ -519,7 +506,6 @@
 			buildActionMask = 2147483647;
 			files = (
 				E205C6F91F1C030E007C139E /* Random.swift in Sources */,
-				E205C6FA1F1C030E007C139E /* Entropy.swift in Sources */,
 				E2D2DD491F436AB7006846F7 /* CharSet.swift in Sources */,
 				E21779CA1F3E7E260019CC42 /* Bytes.swift in Sources */,
 			);
@@ -530,7 +516,6 @@
 			buildActionMask = 2147483647;
 			files = (
 				E2E140551F422FB1003E02B0 /* RandomTests.swift in Sources */,
-				E2E140511F422C70003E02B0 /* EntropyTests.swift in Sources */,
 				E2E140591F433A6D003E02B0 /* CharSetTests.swift in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
@@ -540,7 +525,6 @@
 			buildActionMask = 2147483647;
 			files = (
 				E21779CB1F3E7E260019CC42 /* Bytes.swift in Sources */,
-				E2D2DD461F436A5F006846F7 /* Entropy.swift in Sources */,
 				E2D2DD4A1F436AB8006846F7 /* CharSet.swift in Sources */,
 				E2D2DD471F436AB3006846F7 /* Random.swift in Sources */,
 			);
@@ -552,7 +536,6 @@
 			files = (
 				E2B8C8171F3E2B8500171502 /* CharSet.swift in Sources */,
 				E287ADAE1F0E9DDC00DE6DF5 /* Random.swift in Sources */,
-				E287ADB91F0EDCAB00DE6DF5 /* Entropy.swift in Sources */,
 				E21779C81F3E7E260019CC42 /* Bytes.swift in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
@@ -562,7 +545,6 @@
 			buildActionMask = 2147483647;
 			files = (
 				E2E140531F422FB1003E02B0 /* RandomTests.swift in Sources */,
-				E2E1404F1F422C70003E02B0 /* EntropyTests.swift in Sources */,
 				E2E140571F433A6D003E02B0 /* CharSetTests.swift in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;

README.md

@@ -148,23 +148,23 @@ Or perhaps you need a 256 bit token using [RFC 4648](https://tools.ietf.org/html
 
 ### <a name="Overview"></a>Overview
 
-`EntropyString` provides easy creation of randomly generated strings of specific entropy using various character sets. Such strings are needed as unique identifiers when generating, for example, random IDs and you don't want the overkill of a GUID.
+`EntropyString` provides easy creation of randomly generated strings of specific entropy using various character sets. Such strings are needed as unique identifiers when generating, for example, random IDs and you don't want the overkill of a UUID.
 
-A key concern when generating such strings is that they be unique. Guaranteed uniqueness, however,, requires either deterministic generation (e.g., a counter) that is not random, or that each newly created random string be compared against all existing strings. When ramdoness is required, the overhead of storing and comparing strings is often too onerous and a different tack is chosen.
+A key concern when generating such strings is that they be unique. Guaranteed uniqueness, however, requires either deterministic generation (e.g., a counter) that is not random, or that each newly created random string be compared against all existing strings. When randomness is required, the overhead of storing and comparing strings is often too onerous and a different tack is chosen.
 
-A common strategy is to replace the *guarantee of uniqueness* with a weaker but often sufficient *probabilistic uniqueness*. Specifically, rather than being absolutely sure of uniqueness, we settle for a statement such as *"there is less than a 1 in a billion chance that two of my strings are the same"*. This strategy requires much less overhead, but does require we have some manner of qualifying what we mean by *"there is less than a 1 in a billion chance that 1 million strings of this form will have a repeat"*.
+A common strategy is to replace the **_guarantee of uniqueness_** with a weaker but often sufficient one of **_probabilistic uniqueness_**. Specifically, rather than being absolutely sure of uniqueness, we settle for a statement such as *"there is less than a 1 in a billion chance that two of my strings are the same"*. We use an implicit version of this very strategy every time we use a hash set, where the keys are formed from taking the hash of some value. We *assume* there will be no hash collision using our values, but we **do not** have any true guarantee of uniqueness per se.
 
-Understanding probabilistic uniqueness of random strings requires an understanding of [*entropy*](https://en.wikipedia.org/wiki/Entropy_(information_theory)) and of estimating the probability of a [*collision*](https://en.wikipedia.org/wiki/Birthday_problem#Cast_as_a_collision_problem) (i.e., the probability that two strings in a set of randomly generated strings might be the same). The blog posting [Hash Collision Probabilities](http://preshing.com/20110504/hash-collision-probabilities/) provides an excellent overview of deriving an expression for calculating the probability of a collision in some number of hashes using a perfect hash with an N-bit output. Thef [Entropy Bits](#EntropyBits) section below discribes how `EntropyString` takes this idea a step further to address a common need in generating unique identifiers.
+Fortunately, a probabilistic uniqueness strategy requires much less overhead than guaranteed uniqueness. But it does require we have some manner of qualifying what we mean by *"there is less than a 1 in a billion chance that 1 million strings of this form will have a repeat"*.
 
-We'll begin investigating `EntropyString` by considering our [Real Need](Read%20Need) when generating random strings.
+Understanding probabilistic uniqueness of random strings requires an understanding of [*entropy*](https://en.wikipedia.org/wiki/Entropy_(information_theory)) and of estimating the probability of a [*collision*](https://en.wikipedia.org/wiki/Birthday_problem#Cast_as_a_collision_problem) (i.e., the probability that two strings in a set of randomly generated strings might be the same). The blog post [Hash Collision Probabilities](http://preshing.com/20110504/hash-collision-probabilities/) provides an excellent overview of deriving an expression for calculating the probability of a collision in some number of hashes using a perfect hash with an N-bit output. This is sufficient for understanding the probability of collision given a hash with a **fixed** output of N-bits, but does not provide an answer to qualifying what we mean by *"there is less than a 1 in a billion chance that 1 million strings of this form will have a repeat"*. The [Entropy Bits](#EntropyBits) section below describes how `EntropyString` provides this qualifying measure.
+
+We'll begin investigating `EntropyString` by considering the [Real Need](#RealNeed) when generating random strings.
 
 [TOC](#TOC)
 
 ### <a name="RealNeed"></a>Real Need
 
-Let's start by reflecting on a common statement of need for developers, who might say:
-
-*I need random strings 16 characters long.*
+Let's start by reflecting on the common statement: *I need random strings 16 characters long.*
 
 Okay. There are libraries available that address that exact need. But first, there are some questions that arise from the need as stated, such as:
 
@@ -180,27 +180,29 @@ As for question 2, the developer might respond:
 
 *I need 10,000 of these things*.
 
-Ah, now we're getting somewhere. The answer to question 3 might lead to the further qualification:
+Ah, now we're getting somewhere. The answer to question 3 might lead to a further qualification:
 
 *I need to generate 10,000 random, unique IDs*.
 
-And the cat's out of the bag. We're getting at the real need, and it's not the same as the original statement. The developer needs *uniqueness* across some potential number of strings. The length of the string is a by-product of the uniqueness, not the goal, and should not be the primary specification for the random string.
+And the cat's out of the bag. We're getting at the real need, and it's not the same as the original statement. The developer needs *uniqueness* across a total of some number of strings. The length of the string is a by-product of the uniqueness, not the goal, and should not be the primary specification for the random string.
 
-As noted in the [Overview](Overview), guaranteeing uniqueness is difficult, so we'll replace that declaration with one of *probabilistic uniqueness* by asking:
+As noted in the [Overview](#Overview), guaranteeing uniqueness is difficult, so we'll replace that declaration with one of *probabilistic uniqueness* by asking a fourth question:
 
-  - What risk of a repeat are you willing to accept?
+<ol start=4>
+  <li>What risk of a repeat are you willing to accept?</li>
+</ol>
 
-Probabilistic uniqueness contains risk. That's the price we pay for giving up on the stronger declaration of strict uniqueness. But the developer can quantify an appropriate risk for a particular scenario with a statement like:
+Probabilistic uniqueness contains risk. That's the price we pay for giving up on the stronger declaration of garuanteed uniqueness. But the developer can quantify an appropriate risk for a particular scenario with a statement like:
 
 *I guess I can live with a 1 in a million chance of a repeat*.
 
-So now we've gotten to the developer's real need:
+So now we've finally gotten to the developer's real need:
 
 *I need 10,000 random hexadecimal IDs with less than 1 in a million chance of any repeats*.
 
 Not only is this statement more specific, there is no mention of string length. The developer needs probabilistic uniqueness, and strings are to be used to capture randomness for this purpose. As such, the length of the string is simply a by-product of the encoding used to represent the required uniqueness as a string.
 
-How do you address this need using a library designed to generate strings of specified length?  Well, you don't directly, because that library was designed to answer the originally stated need, not the real need we've uncovered. We need a library that deals with probabilistic uniqueness of a total number of some strings. And that's exactly what `EntropyString` does.
+How do you address this need using a library designed to generate strings of specified length?  Well, you don't, because that library was designed to answer the originally stated need, not the real need we've uncovered. We need a library that deals with probabilistic uniqueness of a total number of some strings. And that's exactly what `EntropyString` does.
 
 Let's use `EntropyString` to help this developer generate 5 hexadecimal IDs from a pool of a potentail 10,000 IDs with a 1 in a milllion chance of a repeat:
 

Sources/CharSet.swift

@@ -79,9 +79,9 @@ public struct CharSet {
 
     self.chars = chars
     bitsPerChar = UInt8(log2(Float(length)))
-    charsPerChunk = CharSet.lcm(bitsPerChar, Entropy.bitsPerByte) / bitsPerChar
+    charsPerChunk = CharSet.lcm(bitsPerChar, Random.bitsPerByte) / bitsPerChar
 
-    if CharSet.lcm(bitsPerChar, Entropy.bitsPerByte) == Entropy.bitsPerByte {
+    if CharSet.lcm(bitsPerChar, Random.bitsPerByte) == Random.bitsPerByte {
       ndxFn = CharSet.ndxFnForDivisor(bitsPerChar)
     }
     else {
@@ -93,7 +93,7 @@ public struct CharSet {
   ///
   public func bytesNeeded(bits: Float) -> Int {
     let count = ceil(bits / Float(bitsPerChar))
-    return Int(ceil(count * Float(bitsPerChar) / Float(Entropy.bitsPerByte)))
+    return Int(ceil(count * Float(bitsPerChar) / Float(Random.bitsPerByte)))
   }
 
   /// Determines index into `CharSet` characters when base is a multiple of 8.
@@ -111,7 +111,7 @@ public struct CharSet {
   private static func ndxFnForDivisor(_ bitsPerChar: UInt8) -> NdxFn {
     func ndxFn(bytes: [UInt8], chunk: Int, slice: UInt8) -> Ndx {
       let lShift = UInt8(bitsPerChar)
-      let rShift = Entropy.bitsPerByte - bitsPerChar
+      let rShift = Random.bitsPerByte - bitsPerChar
       return (bytes[chunk]<<UInt8(slice*lShift))>>rShift
     }
     return ndxFn
@@ -131,7 +131,7 @@ public struct CharSet {
   /// - return: The a function to index into the `CharSet` characters.
   private static func ndxFnForNonDivisor(_ bitsPerChar: UInt8) -> NdxFn {
     func ndxFn(bytes: [UInt8], chunk: Int, slice: UInt8) -> Ndx {
-      let bitsPerByte = Entropy.bitsPerByte
+      let bitsPerByte = Random.bitsPerByte
       let slicesPerChunk = lcm(bitsPerChar, bitsPerByte) / bitsPerByte
       let bNum = chunk * Int(slicesPerChunk)