database/sql: rename NamedParam to NamedArg and Param to Named

Be consistent with the argument names already provided. Also
parameter is the variable, argument is the value.

Fixes #18099

Change-Id: Idb3f4e9ffc214036c721ddb4f614ec6c95bb7778
Reviewed-on: https://go-review.googlesource.com/33660
Run-TryBot: Russ Cox <rsc@golang.org>
Reviewed-by: Russ Cox <rsc@golang.org>

diff --git a/src/database/sql/convert.go b/src/database/sql/convert.go
index 44695b67a616524add6d205a9e51c2da1c8fd1b9..4b4dfc40d7d135aa133badc41d7fb428008185c0 100644 (file)
--- a/src/database/sql/convert.go
+++ b/src/database/sql/convert.go
@@ -42,7 +42,7 @@ func driverArgs(ds *driverStmt, args []interface{}) ([]driver.NamedValue, error)
                        var err error
                        nv := &nvargs[n]
                        nv.Ordinal = n + 1
-                       if np, ok := arg.(NamedParam); ok {
+                       if np, ok := arg.(NamedArg); ok {
                                arg = np.Value
                                nvargs[n].Name = np.Name
                        }
@@ -59,7 +59,7 @@ func driverArgs(ds *driverStmt, args []interface{}) ([]driver.NamedValue, error)
        for n, arg := range args {
                nv := &nvargs[n]
                nv.Ordinal = n + 1
-               if np, ok := arg.(NamedParam); ok {
+               if np, ok := arg.(NamedArg); ok {
                        arg = np.Value
                        nv.Name = np.Name
                }

diff --git a/src/database/sql/sql.go b/src/database/sql/sql.go
index 4ef0fa7221ffe7d093fa4ec5a663546c55fd8e5f..a620707b2d7dfee4692c9e56d174e756a63d979c 100644 (file)
--- a/src/database/sql/sql.go
+++ b/src/database/sql/sql.go
@@ -69,9 +69,9 @@ func Drivers() []string {
        return list
 }
 
-// NamedParam may be passed into query parameter arguments to associate
-// a named placeholder with a value.
-type NamedParam struct {
+// A NamedArg used as an argument to Query or Exec
+// binds to the corresponding named parameter in the SQL statement.
+type NamedArg struct {
        _Named_Fields_Required struct{}
 
        // Name of the parameter placeholder. If empty the ordinal position in the
@@ -83,13 +83,24 @@ type NamedParam struct {
        Value interface{}
 }
 
-// Param provides a more concise way to create NamedParam values.
-func Param(name string, value interface{}) NamedParam {
+// Named provides a more concise way to create NamedArg values.
+//
+// Example usage:
+//
+//     db.ExecContext(ctx, `
+//         delete from Invoice
+//         where
+//             TimeCreated < @end
+//             and TimeCreated >= @start;`,
+//         sql.Named("start", startTime),
+//         sql.Named("end", endTime),
+//     )
+func Named(name string, value interface{}) NamedArg {
        // This method exists because the go1compat promise
        // doesn't guarantee that structs don't grow more fields,
        // so unkeyed struct literals are a vet error. Thus, we don't
-       // want to encourage sql.NamedParam{name, value}.
-       return NamedParam{Name: name, Value: value}
+       // want to allow sql.NamedArg{name, value}.
+       return NamedArg{Name: name, Value: value}
 }
 
 // IsolationLevel is the transaction isolation level stored in Context.

diff --git a/src/database/sql/sql_test.go b/src/database/sql/sql_test.go
index d94ef5cad3f0f040013d359a3865cb79c2dd7b92..c0f2cf29095ca1924435e95aa09a4db59fb4760f 100644 (file)
--- a/src/database/sql/sql_test.go
+++ b/src/database/sql/sql_test.go
@@ -468,15 +468,15 @@ func TestMultiResultSetQuery(t *testing.T) {
        }
 }
 
-func TestQueryNamedParam(t *testing.T) {
+func TestQueryNamedArg(t *testing.T) {
        db := newTestDB(t, "people")
        defer closeDB(t, db)
        prepares0 := numPrepares(t, db)
        rows, err := db.Query(
                // Ensure the name and age parameters only match on placeholder name, not position.
                "SELECT|people|age,name|name=?name,age=?age",
-               Param("?age", 2),
-               Param("?name", "Bob"),
+               Named("?age", 2),
+               Named("?name", "Bob"),
        )
        if err != nil {
                t.Fatalf("Query: %v", err)