DOCSP-13861 replace usage example (#23)

* added replace usage example page

Author: kyuan-mongodb

source/includes/usage-examples/code-snippets/replace.go

@@ -0,0 +1,47 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+
+	"go.mongodb.org/mongo-driver/bson"
+	"go.mongodb.org/mongo-driver/mongo"
+	"go.mongodb.org/mongo-driver/mongo/options"
+)
+
+func main() {
+
+	var uri string
+	if uri = os.Getenv("MONGODB_URI"); uri == "" {
+		log.Fatal("You must set your `MONGODB_URI' environmental variable. See\n\t https://docs.mongodb.com/drivers/go/current/usage-examples/")
+	}
+
+	client, err := mongo.Connect(context.TODO(), options.Client().ApplyURI(uri))
+	if err != nil {
+		panic(err)
+	}
+	defer func() {
+		if err = client.Disconnect(context.TODO()); err != nil {
+			panic(err)
+		}
+	}()
+
+	// begin replace
+	coll := client.Database("insertDB").Collection("haikus")
+	filter := bson.D{{"title", "Record of a Shriveled Datum"}}
+	replacement := bson.D{{"title", "Dodging Greys"}, {"text", "When there're no matches, no longer need to panic. You can use upsert"}}
+
+	result, err := coll.ReplaceOne(context.TODO(), filter, replacement)
+	// end replace
+
+	if err != nil {
+		panic(err)
+	}
+
+	// When you run this file for the first time, it should print: "Number of documents replaced: 1"
+	if result.MatchedCount != 0 {
+		fmt.Println("Number of documents replaced: %d\n", result.ModifiedCount)
+	}
+}

source/usage-examples/replaceOne.txt

@@ -3,3 +3,53 @@ Replace a Document
 ==================
 
 .. default-domain:: mongodb
+
+You can replace a document in a collection by using the ``ReplaceOne()``
+method. 
+
+The following example specifies a query filter and replacement document
+to the ``ReplaceOne()`` method, which matches a document in the
+``haikus`` collection where the ``title`` field is "Record of a
+Shriveled Datum" and replaces it with a document that contains a
+``title`` and ``text`` field about a haiku: 
+
+.. include:: /includes/usage-examples/run-example-tip.rst
+
+.. literalinclude:: /includes/usage-examples/code-snippets/replace.go
+   :start-after: begin replace
+   :end-before: end replace
+   :emphasize-lines: 5
+   :language: go
+   :dedent:
+
+Click `here <{+example+}/replace.go>`__  to see a fully runnable example.
+
+Expected Result
+---------------
+
+After you run the preceding code snippet, you should be able to find the
+replacement document in the ``haikus`` collection: 
+
+.. code-block:: json
+   :copyable: false
+
+   { 
+      "_id" : ObjectId("..."),
+      "title" : "Dodging Greys",
+      "text" : "When there're no matches, no longer need to panic. You can use upsert."
+   }
+
+For an example on how to find a document, see our :doc:`Find
+One Usage Example </usage-examples/findOne>`.
+
+Additional Information
+----------------------
+
+For more information on replacing documents, specifying query filters, and
+handling potential errors, see our guide on **<TODO: change a document
+fundamental page>**.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+`ReplaceOne() <{+godocs+}/mongo#Collection.ReplaceOne>`__