Add Go implementation

Author: oxhacks

README.rst

@@ -43,6 +43,9 @@ Implementations
 -  `javascript
    time-hash <https://github.com/disarticulate/time-hash>`__
    - port of reference implements
+-  `golang
+   timehash <https://github.com/abeusher/timehash/blob/master/timehash.go>`__
+   - a reference implementation in Go
 
 Usage
 -----

timehash.go

@@ -0,0 +1,202 @@
+/*
+This module creates a fuzzy precision representation of a time interval.
+- It makes calculations based on a 64 year representation of time from January 1, 1970 to January 1, 2098.
+- Values are encoded with a number of bits(represented by an ASCII character) that indicate the amount of time to add to 1970.
+- Times prior to 1970 or after 2098 are not accounted for by this scale.
+- Each character added to the timehash reduces the time interval ambiguity by a factor of 8.
+- Valid characters for encoding the floating point time into ASCII characters include {01abcdef}
+
+0 +/- 64 years
+1 +/- 8 years
+2 +/- 1 years
+3 +/- 45.65625 days
+4 +/- 5.707 days
+5 +/- 0.71337 days = 17.121 hours
+6 +/- 2.14013671875 hours
+7 +/- 0.26751708984375 hours = 16.05 minutes
+8 +/- 2.006378173828125 minutes
+9 +/- 0.2507 minutes = 15 seconds
+10 +/- 1.88097 seconds
+*/
+
+package main
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+)
+
+const _base32 string = "01abcdef"
+const mapBefore string = "f01abcde"
+const mapAfter string = "1abcdef0"
+const lowerBound float64 = 0.0
+const upperBound float64 = 4039372800.0
+const defaultPrecision int = 10
+
+var bits = [3]int{4, 2, 1}
+var decodeMap = make(map[string]int)
+var neighborMap = make(map[string]Neighbor)
+
+// Neighbor holds the timehash before, during, and after
+// the given window to exclude the given timehash.
+type Neighbor struct {
+	before string
+	after  string
+}
+
+// Neighborhood holds the timehash before, during, and after
+// the given window to include the given timehash.
+type Neighborhood struct {
+	before string
+	center string
+	after  string
+}
+
+func main() {
+	initMaps()
+	examples()
+}
+
+func examples() {
+	testHash := "af1cef0" // '2016-05-27T01:55:57.202148'
+	th, slop := DecodeExactly(testHash)
+	ths := strconv.FormatFloat(th, 'f', 7, 64)
+	slops := strconv.FormatFloat(slop, 'f', 7, 64)
+	fmt.Print("Encoded with margin ", ths, slops, "\n")
+	fmt.Print("Encoded ", Encode(1516933969.398167, defaultPrecision), "\n")
+	fmt.Print("Before ", Before(testHash), "\n")
+	fmt.Print("After: ", After(testHash), "\n")
+	fmt.Print("Encode from datetime ", EncodeDate(time.Now()), "\n")
+}
+
+func initMaps() {
+	for i := range _base32 {
+		decodeMap[string(_base32[i])] = i
+		neighborMap[string(_base32[i])] = Neighbor{string(mapBefore[i]), string(mapAfter[i])}
+	}
+	fmt.Println(decodeMap)
+}
+
+// DecodeExactly decodes a timehash and get the margin of error
+// on that calculation in seconds.
+func DecodeExactly(timehash string) (float64, float64) {
+	lower, upper := lowerBound, upperBound
+	var mid float64
+	timeError := (lower + upper) / 2
+
+	for _, c := range timehash {
+		dc := decodeMap[string(c)]
+		for _, mask := range bits {
+			timeError = timeError / 2
+			mid = (lower + upper) / 2
+
+			if mask&dc > 0 {
+				lower = mid
+			} else {
+				upper = mid
+			}
+		}
+	}
+
+	value := (lower + upper) / 2
+	return value, timeError
+}
+
+// Decode the geohash but throw away the margin of error.
+func Decode(timehash string) float64 {
+	epochSeconds, _ := DecodeExactly(timehash)
+	return epochSeconds
+}
+
+// Encode the given seconds since the epoch into a timehash
+// at the given precision.
+func Encode(epochSeconds float64, precision int) string {
+	// If no precision offered (zero value), default to 10.
+	if precision == 0 {
+		precision = defaultPrecision
+	}
+	var timehash []string
+	var ch, bit int
+	lower, upper := lowerBound, upperBound
+
+	for len(timehash) < precision {
+		mid := (lower + upper) / 2
+		if epochSeconds > mid {
+			ch = ch | bits[bit]
+			lower = mid
+		} else {
+			upper = mid
+		}
+		if bit < 2 {
+			bit = bit + 1
+		} else {
+			timehash = append(timehash, string(_base32[ch]))
+			bit = 0
+			ch = 0
+		}
+	}
+
+	return strings.Join(timehash, "")
+}
+
+// Before determines the timehash for the window directly
+// preceding the given timehash at the same precision.
+func Before(timehash string) string {
+	i := 1
+	var value string
+
+	for j := len(timehash) - 1; j >= 0; j-- {
+		c := string(timehash[j])
+		if c != "0" {
+			padding := strings.Repeat("f", i-1)
+			position := len(timehash) - i
+			value = timehash[0:position] + neighborMap[c].before + padding
+			break
+		} else {
+			i = i + 1
+		}
+	}
+
+	return value
+}
+
+// After determines the timehash for the window directly
+// after the given timehash at the same precision.
+func After(timehash string) string {
+	i := 1
+	var value string
+
+	for j := len(timehash) - 1; j >= 0; j-- {
+		c := string(timehash[j])
+		if c != "f" {
+			padding := strings.Repeat("0", i-1)
+			position := len(timehash) - i
+			value = timehash[0:position] + neighborMap[c].after + padding
+			break
+		} else {
+			i = i + 1
+		}
+	}
+
+	return value
+}
+
+// Neighbors returns the neighboring windows to either side
+// of the provided timehash at the same precision.
+func Neighbors(timehash string) Neighbor {
+	return Neighbor{Before(timehash), After(timehash)}
+}
+
+// Expand the given timehash window to include the preceding
+// and following window, including the given timehash.
+func Expand(timehash string) Neighborhood {
+	return Neighborhood{Before(timehash), timehash, After(timehash)}
+}
+
+// EncodeDate takes a Time object and turns it into a
+// timehash at the default precision.
+func EncodeDate(date time.Time) string {
+	return Encode(float64(date.Unix()), defaultPrecision)
+}