Add examples

rows_test.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"os"
 	"testing"
+	"time"
 
 	"github.com/jackc/pgx/v5"
 	"github.com/jackc/pgx/v5/pgconn"
@@ -147,6 +148,35 @@ func TestCollectRows(t *testing.T) {
 	})
 }
 
+// This example uses CollectRows with a manually written collector function. In most cases RowTo, RowToAddrOf,
+// RowToStructByPos, RowToAddrOfStructByPos, or another generic function would be used.
+func ExampleCollectRows() {
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	conn, err := pgx.Connect(ctx, os.Getenv("PGX_TEST_DATABASE"))
+	if err != nil {
+		fmt.Printf("Unable to establish connection: %v", err)
+		return
+	}
+
+	rows, _ := conn.Query(ctx, `select n from generate_series(1, 5) n`)
+	numbers, err := pgx.CollectRows(rows, func(row pgx.CollectableRow) (int32, error) {
+		var n int32
+		err := row.Scan(&n)
+		return n, err
+	})
+	if err != nil {
+		fmt.Printf("CollectRows error: %v", err)
+		return
+	}
+
+	fmt.Println(numbers)
+
+	// Output:
+	// [1 2 3 4 5]
+}
+
 func TestCollectOneRow(t *testing.T) {
 	defaultConnTestRunner.RunTest(context.Background(), t, func(ctx context.Context, t testing.TB, conn *pgx.Conn) {
 		rows, _ := conn.Query(ctx, `select 42`)
@@ -201,6 +231,29 @@ func TestRowTo(t *testing.T) {
 	})
 }
 
+func ExampleRowTo() {
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	conn, err := pgx.Connect(ctx, os.Getenv("PGX_TEST_DATABASE"))
+	if err != nil {
+		fmt.Printf("Unable to establish connection: %v", err)
+		return
+	}
+
+	rows, _ := conn.Query(ctx, `select n from generate_series(1, 5) n`)
+	numbers, err := pgx.CollectRows(rows, pgx.RowTo[int32])
+	if err != nil {
+		fmt.Printf("CollectRows error: %v", err)
+		return
+	}
+
+	fmt.Println(numbers)
+
+	// Output:
+	// [1 2 3 4 5]
+}
+
 func TestRowToAddrOf(t *testing.T) {
 	defaultConnTestRunner.RunTest(context.Background(), t, func(ctx context.Context, t testing.TB, conn *pgx.Conn) {
 		rows, _ := conn.Query(ctx, `select n from generate_series(0, 99) n`)
@@ -214,6 +267,35 @@ func TestRowToAddrOf(t *testing.T) {
 	})
 }
 
+func ExampleRowToAddrOf() {
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	conn, err := pgx.Connect(ctx, os.Getenv("PGX_TEST_DATABASE"))
+	if err != nil {
+		fmt.Printf("Unable to establish connection: %v", err)
+		return
+	}
+
+	rows, _ := conn.Query(ctx, `select n from generate_series(1, 5) n`)
+	pNumbers, err := pgx.CollectRows(rows, pgx.RowToAddrOf[int32])
+	if err != nil {
+		fmt.Printf("CollectRows error: %v", err)
+		return
+	}
+
+	for _, p := range pNumbers {
+		fmt.Println(*p)
+	}
+
+	// Output:
+	// 1
+	// 2
+	// 3
+	// 4
+	// 5
+}
+
 func TestRowToMap(t *testing.T) {
 	defaultConnTestRunner.RunTest(context.Background(), t, func(ctx context.Context, t testing.TB, conn *pgx.Conn) {
 		rows, _ := conn.Query(ctx, `select 'Joe' as name, n as age from generate_series(0, 9) n`)
@@ -228,7 +310,7 @@ func TestRowToMap(t *testing.T) {
 	})
 }
 
-func TestRowToStructPos(t *testing.T) {
+func TestRowToStructByPos(t *testing.T) {
 	type person struct {
 		Name string
 		Age  int32
@@ -247,6 +329,58 @@ func TestRowToStructPos(t *testing.T) {
 	})
 }
 
+func ExampleRowToStructByPos() {
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	conn, err := pgx.Connect(ctx, os.Getenv("PGX_TEST_DATABASE"))
+	if err != nil {
+		fmt.Printf("Unable to establish connection: %v", err)
+		return
+	}
+
+	// Setup example schema and data.
+	_, err = conn.Exec(ctx, `
+create temporary table products (
+	id int primary key generated by default as identity,
+	name varchar(100) not null,
+	price int not null
+);
+
+insert into products (name, price) values
+	('Cheeseburger', 10),
+	('Double Cheeseburger', 14),
+	('Fries', 5),
+	('Soft Drink', 3);
+`)
+	if err != nil {
+		fmt.Printf("Unable to setup example schema and data: %v", err)
+		return
+	}
+
+	type product struct {
+		ID    int32
+		Name  string
+		Price int32
+	}
+
+	rows, _ := conn.Query(ctx, "select * from products where price < $1 order by price desc", 12)
+	products, err := pgx.CollectRows(rows, pgx.RowToStructByPos[product])
+	if err != nil {
+		fmt.Printf("CollectRows error: %v", err)
+		return
+	}
+
+	for _, p := range products {
+		fmt.Printf("%s: $%d\n", p.Name, p.Price)
+	}
+
+	// Output:
+	// Cheeseburger: $10
+	// Fries: $5
+	// Soft Drink: $3
+}
+
 func TestRowToAddrOfStructPos(t *testing.T) {
 	type person struct {
 		Name string