initial commit

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016 Dynamic Network Services Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,2 +1,95 @@
 # qstring
-Golang HTTP Query String Marshaler/Unmarshaler
+The package provides an easy way to marshal and unmarshal query string data to
+and from structs.
+
+# Installation
+```bash
+$ go get github.com/dyninc/qstring
+```
+
+# Example
+
+## Literal
+
+```go
+package main
+
+import (
+	"net/http"
+
+	"github.com/dyninc/qstring"
+)
+
+// Query is the request query struct.
+type Query struct {
+	Names    []string
+	Limit     int
+	Page      int
+}
+
+func handler(w http.ResponseWriter, req *http.Request) {
+	query := &Query{}
+  err := qstring.Unmarshal(req.Url.Query(), query)
+  if err != nil {
+    http.Error(w, err.Error(), http.StatusBadRequest)
+  }
+
+  // ... run conditional logic based on provided query parameters
+}
+```
+
+## Nested
+In the same spirit as other Unmarshalling libraries, `qstring` allows you to
+Marshal/Unmarshal nested structs
+
+```go
+package main
+
+import (
+	"net/http"
+
+	"github.com/dyninc/qstring"
+)
+
+// PagingParams represents common pagination information for query strings
+type PagingParams struct {
+  Page int
+  Limit int
+}
+
+// Req is the request query struct.
+type Query struct {
+  Names    []string
+  PageInfo PagingParams
+}
+```
+
+## Complex Structures
+Again, in the spirit of other Unmarshalling libraries, `qstring` allows for some
+more complex types, such as pointers and time.Time fields. *Note: All Timestamps
+are assumed to be in RFC3339 format*.
+
+```go
+package main
+
+import (
+	"net/http"
+  "time"
+
+	"github.com/dyninc/qstring"
+)
+
+// PagingParams represents common pagination information for query strings
+type PagingParams struct {
+  Page int
+  Limit int
+}
+
+// Req is the request query struct.
+type Query struct {
+  Names    []string
+  PageInfo *PagingParams
+  Created  time.TIme
+  Modified time.Time
+}
+```

bench_test.go

@@ -0,0 +1,52 @@
+package qstring
+
+import (
+	"net/url"
+	"testing"
+)
+
+// Straight benchmark literal.
+func BenchmarkUnmarshall(b *testing.B) {
+	query := url.Values{
+		"limit":  []string{"10"},
+		"page":   []string{"1"},
+		"fields": []string{"a", "b", "c"},
+	}
+	type QueryStruct struct {
+		Fields []string
+		Limit  int
+		Page   int
+	}
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		data := &QueryStruct{}
+		err := Unmarshal(query, data)
+		if err != nil {
+			b.Fatal(err)
+		}
+	}
+}
+
+// Parallel benchmark literal.
+func BenchmarkRawPLiteral(b *testing.B) {
+	query := url.Values{
+		"limit":  []string{"10"},
+		"page":   []string{"1"},
+		"fields": []string{"a", "b", "c"},
+	}
+	type QueryStruct struct {
+		Fields []string
+		Limit  int
+		Page   int
+	}
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		for pb.Next() {
+			data := &QueryStruct{}
+			err := Unmarshal(query, data)
+			if err != nil {
+				b.Fatal(err)
+			}
+		}
+	})
+}