From 293c6dafcae3de7013daf7e16a73c40bb98cf256 Mon Sep 17 00:00:00 2001 From: Simon Jones <18755725+simon-a-j@users.noreply.github.com> Date: Sun, 17 Oct 2021 19:36:46 +0100 Subject: [PATCH] Clarify examples in documentation --- docs/inserting.md | 29 ++++++++++++++++++--------- docs/updating.md | 36 ++++++++++++++++++++++------------ insert_dataset_example_test.go | 32 +++++++++++++++++++++--------- update_dataset_example_test.go | 32 +++++++++++++++++++++--------- 4 files changed, 90 insertions(+), 39 deletions(-) diff --git a/docs/inserting.md b/docs/inserting.md index 802306b1..5e07a363 100644 --- a/docs/inserting.md +++ b/docs/inserting.md @@ -185,9 +185,15 @@ type item struct { Address2 *string `db:"address2" goqu:"omitnil"` Address3 *string `db:"address3" goqu:"omitnil"` } -testString := "Test" -emptyString := "" -i := item{FirstName: "Test", Address1: &testString, Address2: &emptyString} +address1 := "111 Test Addr" +var emptyString string +i := item{ + FirstName: "Test First Name", + LastName: "", + Address1: &address1, + Address2: &emptyString, + Address3: nil, // will omit nil pointer +} insertSQL, args, _ := goqu.Insert("items").Rows(i).ToSQL() fmt.Println(insertSQL, args) @@ -195,7 +201,7 @@ fmt.Println(insertSQL, args) Output: ``` -INSERT INTO "items" ("address1", "address2", "first_name", "last_name") VALUES ('Test', '', 'Test', '') [] +INSERT INTO "items" ("address1", "address2", "first_name", "last_name") VALUES ('111 Test Addr', '', 'Test First Name', '') [] ``` If you do not want to set the database field when the struct field is a zero value (including nil pointers) you can use @@ -211,17 +217,22 @@ type item struct { Address2 *string `db:"address2" goqu:"omitempty"` Address3 *string `db:"address3" goqu:"omitempty"` } -testString := "Test" -emptyString := "" -i := item{FirstName: "Test", Address1: &testString, Address2: &emptyString} - +address1 := "112 Test Addr" +var emptyString string +i := item{ + FirstName: "Test First Name", + LastName: "", // will omit zero field + Address1: &address1, + Address2: &emptyString, + Address3: nil, // will omit nil pointer +} insertSQL, args, _ := goqu.Insert("items").Rows(i).ToSQL() fmt.Println(insertSQL, args) ``` Output: ``` -INSERT INTO "items" ("address1", "address2", "first_name") VALUES ('Test', '', 'Test') [] +INSERT INTO "items" ("address1", "address2", "first_name") VALUES ('112 Test Addr', '', 'Test First Name') [] ``` If you want to use the database `DEFAULT` when the struct field is a zero value you can use the `defaultifempty` tag. diff --git a/docs/updating.md b/docs/updating.md index 52f2468a..d22cbf7d 100644 --- a/docs/updating.md +++ b/docs/updating.md @@ -165,17 +165,23 @@ type item struct { Address2 *string `db:"address2" goqu:"omitnil"` Address3 *string `db:"address3" goqu:"omitnil"` } -testString := "Test" -emptyString := "" -query, args, _ := goqu.Update("items").Set( - item{FirstName: "Test", Address1: &testString, Address2: &emptyString}, +address1 := "113 Test Addr" +var emptyString string +sql, args, _ := goqu.Update("items").Set( + item{ + FirstName: "Test First Name", + LastName: "", + Address1: &address1, + Address2: &emptyString, + Address3: nil, // will omit nil pointer + }, ).ToSQL() -fmt.Println(query, args) +fmt.Println(sql, args) ``` Output: ``` -UPDATE "items" SET "address1"='Test',"address2"='',"first_name"='Test',"last_name"='' [] +UPDATE "items" SET "address1"='113 Test Addr',"address2"='',"first_name"='Test First Name',"last_name"='' [] ``` If you do not want to update the database field when the struct field is a zero value (including nil pointers) you can @@ -191,17 +197,23 @@ type item struct { Address2 *string `db:"address2" goqu:"omitempty"` Address3 *string `db:"address3" goqu:"omitempty"` } -testString := "Test" -emptyString := "" -query, args, _ := goqu.Update("items").Set( - item{FirstName: "Test", Address1: &testString, Address2: &emptyString}, +address1 := "114 Test Addr" +var emptyString string +sql, args, _ := goqu.Update("items").Set( + item{ + FirstName: "Test First Name", + LastName: "", // will omit zero field + Address1: &address1, + Address2: &emptyString, + Address3: nil, // will omit nil pointer + }, ).ToSQL() -fmt.Println(query, args) +fmt.Println(sql, args) ``` Output: ``` -UPDATE "items" SET "address1"='Test',"address2"='',"first_name"='Test' [] +UPDATE "items" SET "address1"='114 Test Addr',"address2"='',"first_name"='Test First Name' [] ``` If you want to use the database `DEFAULT` when the struct field is a zero value you can use the `defaultifempty` tag. diff --git a/insert_dataset_example_test.go b/insert_dataset_example_test.go index 7b37236d..755b3d69 100644 --- a/insert_dataset_example_test.go +++ b/insert_dataset_example_test.go @@ -385,15 +385,21 @@ func ExampleInsertDataset_Rows_withOmitNilTag() { Address2 *string `db:"address2" goqu:"omitnil"` Address3 *string `db:"address3" goqu:"omitnil"` } - address := "111 Test Addr" + address1 := "111 Test Addr" var emptyString string - i := item{FirstName: "Test", Address1: &address, Address2: &emptyString} + i := item{ + FirstName: "Test First Name", + LastName: "", + Address1: &address1, + Address2: &emptyString, + Address3: nil, // will omit nil pointer + } insertSQL, args, _ := goqu.Insert("items").Rows(i).ToSQL() fmt.Println(insertSQL, args) // Output: - // INSERT INTO "items" ("address1", "address2", "first_name", "last_name") VALUES ('111 Test Addr', '', 'Test', '') [] + // INSERT INTO "items" ("address1", "address2", "first_name", "last_name") VALUES ('111 Test Addr', '', 'Test First Name', '') [] } func ExampleInsertDataset_Rows_withOmitEmptyTag() { @@ -404,14 +410,20 @@ func ExampleInsertDataset_Rows_withOmitEmptyTag() { Address2 *string `db:"address2" goqu:"omitempty"` Address3 *string `db:"address3" goqu:"omitempty"` } - address := "112 Test Addr" + address1 := "112 Test Addr" var emptyString string - i := item{FirstName: "Test", Address1: &address, Address2: &emptyString} + i := item{ + FirstName: "Test First Name", + LastName: "", // will omit zero field + Address1: &address1, + Address2: &emptyString, + Address3: nil, // will omit nil pointer + } insertSQL, args, _ := goqu.Insert("items").Rows(i).ToSQL() fmt.Println(insertSQL, args) // Output: - // INSERT INTO "items" ("address1", "address2", "first_name") VALUES ('112 Test Addr', '', 'Test') [] + // INSERT INTO "items" ("address1", "address2", "first_name") VALUES ('112 Test Addr', '', 'Test First Name') [] } func ExampleInsertDataset_Rows_withOmitEmptyTag_Valuer() { @@ -425,17 +437,19 @@ func ExampleInsertDataset_Rows_withOmitEmptyTag_Valuer() { Address4 *sql.NullString `db:"address4" goqu:"omitempty"` } i := item{ - FirstName: sql.NullString{Valid: true, String: "Test"}, + FirstName: sql.NullString{Valid: true, String: "Test First Name"}, MiddleName: sql.NullString{Valid: true, String: ""}, - Address1: &sql.NullString{Valid: true, String: "Test"}, + LastName: sql.NullString{}, // will omit zero valuer struct + Address1: &sql.NullString{Valid: true, String: "Test Address 1"}, Address2: &sql.NullString{Valid: true, String: ""}, Address3: &sql.NullString{}, + Address4: nil, // will omit nil pointer } insertSQL, args, _ := goqu.Insert("items").Rows(i).ToSQL() fmt.Println(insertSQL, args) // Output: - // INSERT INTO "items" ("address1", "address2", "address3", "first_name", "middle_name") VALUES ('Test', '', NULL, 'Test', '') [] + // INSERT INTO "items" ("address1", "address2", "address3", "first_name", "middle_name") VALUES ('Test Address 1', '', NULL, 'Test First Name', '') [] } func ExampleInsertDataset_Rows_withGoquDefaultIfEmptyTag() { diff --git a/update_dataset_example_test.go b/update_dataset_example_test.go index 8664aee6..096dfa38 100644 --- a/update_dataset_example_test.go +++ b/update_dataset_example_test.go @@ -31,15 +31,21 @@ func ExampleUpdate_withOmitNilTag() { Address2 *string `db:"address2" goqu:"omitnil"` Address3 *string `db:"address3" goqu:"omitnil"` } - address := "113 Test Addr" + address1 := "113 Test Addr" var emptyString string sql, args, _ := goqu.Update("items").Set( - item{FirstName: "Test", Address1: &address, Address2: &emptyString}, + item{ + FirstName: "Test First Name", + LastName: "", + Address1: &address1, + Address2: &emptyString, + Address3: nil, // will omit nil pointer + }, ).ToSQL() fmt.Println(sql, args) // Output: - // UPDATE "items" SET "address1"='113 Test Addr',"address2"='',"first_name"='Test',"last_name"='' [] + // UPDATE "items" SET "address1"='113 Test Addr',"address2"='',"first_name"='Test First Name',"last_name"='' [] } func ExampleUpdate_withOmitEmptyTag() { @@ -50,15 +56,21 @@ func ExampleUpdate_withOmitEmptyTag() { Address2 *string `db:"address2" goqu:"omitempty"` Address3 *string `db:"address3" goqu:"omitempty"` } - address := "114 Test Addr" + address1 := "114 Test Addr" var emptyString string sql, args, _ := goqu.Update("items").Set( - item{FirstName: "Test", Address1: &address, Address2: &emptyString}, + item{ + FirstName: "Test First Name", + LastName: "", // will omit zero field + Address1: &address1, + Address2: &emptyString, + Address3: nil, // will omit nil pointer + }, ).ToSQL() fmt.Println(sql, args) // Output: - // UPDATE "items" SET "address1"='114 Test Addr',"address2"='',"first_name"='Test' [] + // UPDATE "items" SET "address1"='114 Test Addr',"address2"='',"first_name"='Test First Name' [] } func ExampleUpdate_withOmitEmptyTag_valuer() { @@ -73,17 +85,19 @@ func ExampleUpdate_withOmitEmptyTag_valuer() { } query, args, _ := goqu.Update("items").Set( item{ - FirstName: dbsql.NullString{Valid: true, String: "Test"}, + FirstName: dbsql.NullString{Valid: true, String: "Test First Name"}, MiddleName: dbsql.NullString{Valid: true, String: ""}, - Address1: &dbsql.NullString{Valid: true, String: "Test"}, + LastName: dbsql.NullString{}, // will omit zero valuer struct + Address1: &dbsql.NullString{Valid: true, String: "Test Address 1"}, Address2: &dbsql.NullString{Valid: true, String: ""}, Address3: &dbsql.NullString{}, + Address4: nil, // will omit nil pointer }, ).ToSQL() fmt.Println(query, args) // Output: - // UPDATE "items" SET "address1"='Test',"address2"='',"address3"=NULL,"first_name"='Test',"middle_name"='' [] + // UPDATE "items" SET "address1"='Test Address 1',"address2"='',"address3"=NULL,"first_name"='Test First Name',"middle_name"='' [] } func ExampleUpdate_withGoquRecord() {