Skip to content

Commit

Permalink
Clarify examples in documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@simon-a-j
simon-a-j committed Oct 17, 2021
1 parent 1efcf45 commit 293c6da
Show file tree
Hide file tree
Showing 4 changed files with 90 additions and 39 deletions.
29 changes: 20 additions & 9 deletions docs/inserting.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -185,17 +185,23 @@ 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)
```

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
Expand All @@ -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.
Expand Down
36 changes: 24 additions & 12 deletions docs/updating.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand Down
32 changes: 23 additions & 9 deletions insert_dataset_example_test.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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() {
Expand All @@ -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() {
Expand All @@ -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() {
Expand Down
32 changes: 23 additions & 9 deletions update_dataset_example_test.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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() {
Expand All @@ -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() {
Expand All @@ -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() {
Expand Down

0 comments on commit 293c6da

Please sign in to comment.