From 9fd8d12ce4457992eba1a1bf947377fd475ad22f Mon Sep 17 00:00:00 2001
From: "Derrick J. Wippler" <thrawn01@gmail.com>
Date: Mon, 13 Feb 2017 22:38:15 -0600
Subject: [PATCH] Improved MapScan() documentation and added new MapScan test

---
 cassandra_test.go | 49 ++++++++++++++++++++++++++++++++++++++++++++++-
 helpers.go        | 36 ++++++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+), 1 deletion(-)

diff --git a/cassandra_test.go b/cassandra_test.go
index 6909dfa09..68eaa37f4 100644
--- a/cassandra_test.go
+++ b/cassandra_test.go
@@ -620,7 +620,8 @@ func TestMapScanWithRefMap(t *testing.T) {
 	m["testfullname"] = FullName{"John", "Doe"}
 	m["testint"] = 100
 
-	if err := session.Query(`INSERT INTO scan_map_ref_table (testtext, testfullname, testint) values (?,?,?)`, m["testtext"], m["testfullname"], m["testint"]).Exec(); err != nil {
+	if err := session.Query(`INSERT INTO scan_map_ref_table (testtext, testfullname, testint) values (?,?,?)`,
+		m["testtext"], m["testfullname"], m["testint"]).Exec(); err != nil {
 		t.Fatal("insert:", err)
 	}
 
@@ -646,7 +647,53 @@ func TestMapScanWithRefMap(t *testing.T) {
 			t.Fatal("returned testinit did not match")
 		}
 	}
+	if testText != "testtext" {
+		t.Fatal("returned testtext did not match")
+	}
+	if testFullName.FirstName != "John" || testFullName.LastName != "Doe" {
+		t.Fatal("returned testfullname did not match")
+	}
+}
+
+func TestMapScan(t *testing.T) {
+	session := createSession(t)
+	defer session.Close()
+	if err := createTable(session, `CREATE TABLE gocql_test.scan_map_table (
+			fullname       text PRIMARY KEY,
+			age            int,
+			address        inet,
+		)`); err != nil {
+		t.Fatal("create table:", err)
+	}
+
+	if err := session.Query(`INSERT INTO scan_map_table (fullname, age, address) values (?,?,?)`,
+		"Grace Hopper", 31, net.ParseIP("10.0.0.1")).Exec(); err != nil {
+		t.Fatal("insert:", err)
+	}
+	if err := session.Query(`INSERT INTO scan_map_table (fullname, age, address) values (?,?,?)`,
+		"Ada Lovelace", 30, net.ParseIP("10.0.0.2")).Exec(); err != nil {
+		t.Fatal("insert:", err)
+	}
+
+	iter := session.Query(`SELECT * FROM scan_map_table`).Iter()
 
+	// First iteration
+	row := make(map[string]interface{})
+	if !iter.MapScan(row) {
+		t.Fatal("select:", iter.Close())
+	}
+	assertEqual(t, "fullname", "Ada Lovelace", row["fullname"])
+	assertEqual(t, "age", 30, row["age"])
+	assertEqual(t, "address", "10.0.0.2", row["address"])
+
+	// Second iteration using a new map
+	row = make(map[string]interface{})
+	if !iter.MapScan(row) {
+		t.Fatal("select:", iter.Close())
+	}
+	assertEqual(t, "fullname", "Grace Hopper", row["fullname"])
+	assertEqual(t, "age", 31, row["age"])
+	assertEqual(t, "address", "10.0.0.1", row["address"])
 }
 
 func TestSliceMap(t *testing.T) {
diff --git a/helpers.go b/helpers.go
index dca87b8d8..a58028191 100644
--- a/helpers.go
+++ b/helpers.go
@@ -250,6 +250,42 @@ func (iter *Iter) SliceMap() ([]map[string]interface{}, error) {
 
 // MapScan takes a map[string]interface{} and populates it with a row
 // that is returned from cassandra.
+//
+// Each call to MapScan() must be called with a new map object.
+// During the call to MapScan() any pointers in the existing map
+// are replaced with non pointer types before the call returns
+//
+//	iter := session.Query(`SELECT * FROM mytable`).Iter()
+//	for {
+//		// New map each iteration
+//		row = make(map[string]interface{})
+//		if !iter.MapScan(row) {
+//			break
+//		}
+//		// Do things with row
+//		if fullname, ok := row["fullname"]; ok {
+//			fmt.Printf("Full Name: %s\n", fullname)
+//		}
+//	}
+//
+// You can also pass pointers in the map before each call
+//
+//	var fullName FullName // Implements gocql.Unmarshaler and gocql.Marshaler interfaces
+//	var address net.IP
+//	var age int
+//	iter := session.Query(`SELECT * FROM scan_map_table`).Iter()
+//	for {
+//		// New map each iteration
+//		row := map[string]interface{}{
+//			"fullname": &fullName,
+//			"age":      &age,
+//			"address":  &address,
+//		}
+//		if !iter.MapScan(row) {
+//			break
+//		}
+//		fmt.Printf("First: %s Age: %d Address: %q\n", fullName.FirstName, age, address)
+//	}
 func (iter *Iter) MapScan(m map[string]interface{}) bool {
 	if iter.err != nil {
 		return false