datastore: add new key functions

Add the functions IncompleteKey, NameKey and IDKey.

This is the minimal change that will let people start converting to
avoid breakage. Examples and tests have not been updated.

Change-Id: I0993ed54cc52ab642d088e6df588856f5d22b98a
Reviewed-on: https://code-review.googlesource.com/8994
Reviewed-by: Ross Light <light@google.com>

datastore/datastore_test.go

@@ -1821,3 +1821,26 @@ func (c *fakeDatastoreClient) AllocateIds(ctx context.Context, in *pb.AllocateId
 	}
 	return c.allocateIds(in)
 }
+
+func TestNewKeyFunctions(t *testing.T) {
+	ctx := context.Background()
+	parent := NewKey(ctx, "k", "", 17, nil)
+
+	want := NewIncompleteKey(ctx, "k", parent)
+	got := IncompleteKey("k", parent)
+	if *got != *want {
+		t.Errorf("got %v, want %v", got, want)
+	}
+
+	want = NewKey(ctx, "k", "name", 0, parent)
+	got = NameKey("k", "name", parent)
+	if *got != *want {
+		t.Errorf("got %v, want %v", got, want)
+	}
+
+	want = NewKey(ctx, "k", "", 22, parent)
+	got = IDKey("k", 22, parent)
+	if *got != *want {
+		t.Errorf("got %v, want %v", got, want)
+	}
+}

datastore/key.go

@@ -286,3 +286,37 @@ func (c *Client) AllocateIDs(ctx context.Context, keys []*Key) ([]*Key, error) {
 
 	return multiProtoToKey(resp.Keys)
 }
+
+// IncompleteKey creates a new incomplete key.
+// The supplied kind cannot be empty.
+// The namespace of the new key is empty.
+func IncompleteKey(kind string, parent *Key) *Key {
+	return &Key{
+		kind:   kind,
+		parent: parent,
+	}
+}
+
+// NameKey creates a new key with a name.
+// The supplied kind cannot be empty.
+// The supplied parent must either be a complete key or nil.
+// The namespace of the new key is empty.
+func NameKey(kind, name string, parent *Key) *Key {
+	return &Key{
+		kind:   kind,
+		name:   name,
+		parent: parent,
+	}
+}
+
+// IDKey creates a new key with an ID.
+// The supplied kind cannot be empty.
+// The supplied parent must either be a complete key or nil.
+// The namespace of the new key is empty.
+func IDKey(kind string, id int64, parent *Key) *Key {
+	return &Key{
+		kind:   kind,
+		id:     id,
+		parent: parent,
+	}
+}