Skip to content

Commit 52dcaa1

Browse files
bjoribjori
committed
CDRIVER-1008: Document mongoc_collection_find_and_modify_with_opts
1 parent 1e98e4f commit 52dcaa1

18 files changed

+934
-0
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ example-gridfs
2929
example-matcher
3030
filter-bsondump
3131
find-and-modify
32+
fam
3233
*.gcda
3334
*.gcno
3435
*.gz

‎doc/mongoc_collection_find_and_modify_with_opts.page

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
<?xml version="1.0"?>
2+
<page xmlns="http://projectmallard.org/1.0/"
3+
type="topic"
4+
style="function"
5+
xmlns:api="http://projectmallard.org/experimental/api/"
6+
xmlns:ui="http://projectmallard.org/experimental/ui/"
7+
id="mongoc_collection_find_and_modify_with_opts">
8+
<info><link type="guide" xref="mongoc_collection_t" group="function"/></info>
9+
<title>mongoc_collection_find_and_modify_with_opts()</title>
10+
11+
<section id="synopsis">
12+
<title>Synopsis</title>
13+
<synopsis><code mime="text/x-csrc"><![CDATA[bool
14+
mongoc_collection_find_and_modify_with_opts (mongoc_collection_t *collection,
15+
const bson_t *query,
16+
const mongoc_find_and_modify_opts_t *opts,
17+
bson_t *reply,
18+
bson_error_t *error);
19+
]]></code></synopsis>
20+
<note style="tip"><p>New in mongoc 1.3.0</p></note>
21+
</section>
22+
23+
<section id="parameters">
24+
<title>Parameters</title>
25+
<table>
26+
<tr><td><p>collection</p></td><td><p>A <code xref="mongoc_collection_t">mongoc_collection_t</code>.</p></td></tr>
27+
<tr><td><p>query</p></td><td><p>A <code xref="bson:bson_t">bson_t</code> containing the query to locate target document(s).</p></td></tr>
28+
<tr><td><p>opts</p></td><td><p><code xref="mongoc_find_and_modify_opts_t">find and modify options</code></p></td></tr>
29+
<tr><td><p>reply</p></td><td><p>An optional location for a <code xref="bson:bson_t">bson_t</code> that will be initialized with the result or <code>NULL</code>.</p></td></tr>
30+
<tr><td><p>error</p></td><td><p>An optional location for a <code xref="bson:bson_error_t">bson_error_t</code> or <code>NULL</code>.</p></td></tr>
31+
</table>
32+
</section>
33+
34+
<section id="description">
35+
<title>Description</title>
36+
<p>Update and return an object.</p>
37+
</section>
38+
39+
40+
<section id="errors">
41+
<title>Errors</title>
42+
<p>Errors are propagated via the <code>error</code> parameter.</p>
43+
</section>
44+
45+
<section id="return">
46+
<title>Returns</title>
47+
<p>Returns true on success; false on failure.</p>
48+
</section>
49+
50+
<section id="example">
51+
<title>Example</title>
52+
<p>See <code xref="mongoc_find_and_modify_opts_t#example">mongoc_find_and_modify_opts_t</code></p>
53+
</section>
54+
55+
</page>

‎doc/mongoc_find_and_modify_opts_destroy.page

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
<?xml version="1.0"?>
2+
<page xmlns="http://projectmallard.org/1.0/"
3+
type="topic"
4+
style="function"
5+
xmlns:api="http://projectmallard.org/experimental/api/"
6+
xmlns:ui="http://projectmallard.org/experimental/ui/"
7+
id="mongoc_find_and_modify_opts_destroy">
8+
<info><link type="guide" xref="mongoc_find_and_modify_opts_t" group="function"/></info>
9+
<title>mongoc_find_and_modify_opts_destroy()</title>
10+
11+
<section id="synopsis">
12+
<title>Synopsis</title>
13+
<synopsis><code mime="text/x-csrc"><![CDATA[void
14+
mongoc_find_and_modify_opts_destroy (mongoc_find_and_modify_opts_t *find_and_modify_opts);]]></code></synopsis>
15+
<note style="tip"><p>New in mongoc 1.3.0</p></note>
16+
</section>
17+
18+
<section id="parameters">
19+
<title>Parameters</title>
20+
<table>
21+
<tr><td><p>find_and_modify_opts</p></td><td><p>A <code xref="mongoc_find_and_modify_opts_t">mongoc_find_and_modify_opts_t</code>.</p></td></tr>
22+
</table>
23+
</section>
24+
25+
<section id="description">
26+
<title>Description</title>
27+
<p>Frees all resources associated with the find and modify builder structure.</p>
28+
</section>
29+
30+
</page>

‎doc/mongoc_find_and_modify_opts_new.page

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<?xml version="1.0"?>
2+
<page xmlns="http://projectmallard.org/1.0/"
3+
type="topic"
4+
style="function"
5+
xmlns:api="http://projectmallard.org/experimental/api/"
6+
xmlns:ui="http://projectmallard.org/experimental/ui/"
7+
id="mongoc_find_and_modify_opts_new">
8+
<info><link type="guide" xref="mongoc_find_and_modify_opts_t" group="function"/></info>
9+
<title>mongoc_find_and_modify_opts_new()</title>
10+
11+
<section id="synopsis">
12+
<title>Synopsis</title>
13+
<synopsis><code mime="text/x-csrc"><![CDATA[mongoc_find_and_modify_opts_t *
14+
mongoc_find_and_modify_opts_new (void);
15+
]]></code></synopsis>
16+
<note style="tip"><p>New in mongoc 1.3.0</p></note>
17+
</section>
18+
19+
<section id="return">
20+
<title>Returns</title>
21+
<p>Creates a newly allocated find and modify builder structure that is used to create a findAndModify command. This should be freed with <code xref="mongoc_find_and_modify_opts_destroy">mongoc_find_and_modify_opts_destroy()</code> when no longer in use.</p>
22+
</section>
23+
24+
</page>

‎doc/mongoc_find_and_modify_opts_set_bypass_document_validation.page

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
<?xml version="1.0"?>
2+
<page xmlns="http://projectmallard.org/1.0/"
3+
type="topic"
4+
style="function"
5+
xmlns:api="http://projectmallard.org/experimental/api/"
6+
xmlns:ui="http://projectmallard.org/experimental/ui/"
7+
id="mongoc_find_and_modify_opts_set_bypass_document_validation">
8+
<info><link type="guide" xref="mongoc_find_and_modify_opts_t" group="function"/></info>
9+
<title>mongoc_find_and_modify_opts_set_bypass_document_validation()</title>
10+
11+
<section id="synopsis">
12+
<title>Synopsis</title>
13+
<synopsis><code mime="text/x-csrc"><![CDATA[bool
14+
mongoc_find_and_modify_opts_set_bypass_document_validation (mongoc_find_and_modify_opts_t *opts,
15+
bool bypass);
16+
]]></code></synopsis>
17+
<note style="tip"><p>New in MongoDB 3.2 and mongoc 1.3.0</p></note>
18+
<note style="tip"><p>This option is only available when talking to MongoDB 3.2 and later.</p></note>
19+
</section>
20+
21+
<section id="parameters">
22+
<title>Parameters</title>
23+
<table>
24+
<tr><td><p>opts</p></td><td><p>A <code xref="mongoc_find_and_modify_opts_t">mongoc_find_and_modify_opts_t</code>.</p></td></tr>
25+
<tr><td><p>bypass</p></td><td><p>If the schema validation rules should be ignored.</p></td></tr>
26+
</table>
27+
</section>
28+
29+
<section id="description">
30+
<title>Description</title>
31+
<p>Adds bypassDocumentValidation argument to the builder.</p>
32+
<note style="tip"><p>When authentication is enabled, the authenticated user must have either the "dbadmin" or "restore" roles to bypass document validation.</p></note>
33+
</section>
34+
35+
36+
<section id="return">
37+
<title>Returns</title>
38+
<p>Returns true if it successfully added the option to the builder.</p>
39+
</section>
40+
41+
<section id="example">
42+
<title>Setting bypassDocumentValidation</title>
43+
<screen><code mime="text/x-csrc"><include parse="text" href="../examples/find_and_modify_with_opts/bypass.c" xmlns="http://www.w3.org/2001/XInclude" /></code></screen>
44+
<p>Outputs:</p>
45+
<screen><code mime="text/x-csrc"><![CDATA[{
46+
"lastErrorObject": {
47+
"updatedExisting": true,
48+
"n": 1
49+
},
50+
"value": {
51+
"_id": {
52+
"$oid": "56562a99d13e6d86239c7b00"
53+
},
54+
"age": 34,
55+
"firstname": "Zlatan",
56+
"goals": 342,
57+
"lastname": "Ibrahimovic",
58+
"profession": "Football player",
59+
"position": "striker"
60+
},
61+
"ok": 1
62+
}]]></code></screen>
63+
</section>
64+
65+
66+
</page>

‎doc/mongoc_find_and_modify_opts_set_fields.page

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
<?xml version="1.0"?>
2+
<page xmlns="http://projectmallard.org/1.0/"
3+
type="topic"
4+
style="function"
5+
xmlns:api="http://projectmallard.org/experimental/api/"
6+
xmlns:ui="http://projectmallard.org/experimental/ui/"
7+
id="mongoc_find_and_modify_opts_set_fields">
8+
<info><link type="guide" xref="mongoc_find_and_modify_opts_t" group="function"/></info>
9+
<title>mongoc_find_and_modify_opts_set_fields()</title>
10+
11+
<section id="synopsis">
12+
<title>Synopsis</title>
13+
<synopsis><code mime="text/x-csrc"><![CDATA[bool
14+
mongoc_find_and_modify_opts_set_fields (mongoc_find_and_modify_opts_t *opts,
15+
const bson_t *fields);
16+
]]></code></synopsis>
17+
<note style="tip"><p>New in mongoc 1.3.0</p></note>
18+
</section>
19+
20+
<section id="parameters">
21+
<title>Parameters</title>
22+
<table>
23+
<tr><td><p>opts</p></td><td><p>A <code xref="mongoc_find_and_modify_opts_t">mongoc_find_and_modify_opts_t</code>.</p></td></tr>
24+
<tr><td><p>fields</p></td><td><p>A subset of fields to return. Choose which fields to include by appending <code>{fieldname: 1}</code> for each fieldname, or excluding it with <code>{fieldname: 0}</code>.</p></td></tr>
25+
</table>
26+
</section>
27+
28+
<section id="description">
29+
<title>Description</title>
30+
<p>Adds fields argument to the builder.</p>
31+
</section>
32+
33+
34+
<section id="return">
35+
<title>Returns</title>
36+
<p>Returns true if it successfully added the option to the builder.</p>
37+
</section>
38+
39+
<section id="example">
40+
<title>Setting fields</title>
41+
<screen><code mime="text/x-csrc"><include parse="text" href="../examples/find_and_modify_with_opts/fields.c" xmlns="http://www.w3.org/2001/XInclude" /></code></screen>
42+
<p>Outputs:</p>
43+
<screen><code mime="text/x-csrc"><![CDATA[{
44+
"lastErrorObject": {
45+
"updatedExisting": true,
46+
"n": 1
47+
},
48+
"value": {
49+
"_id": {
50+
"$oid": "56562a99d13e6d86239c7b00"
51+
},
52+
"goals": 343
53+
},
54+
"ok": 1
55+
}]]></code></screen>
56+
</section>
57+
58+
59+
</page>

‎doc/mongoc_find_and_modify_opts_set_flags.page

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
<?xml version="1.0"?>
2+
<page xmlns="http://projectmallard.org/1.0/"
3+
type="topic"
4+
style="function"
5+
xmlns:api="http://projectmallard.org/experimental/api/"
6+
xmlns:ui="http://projectmallard.org/experimental/ui/"
7+
id="mongoc_find_and_modify_opts_set_flags">
8+
<info><link type="guide" xref="mongoc_find_and_modify_opts_t" group="function"/></info>
9+
<title>mongoc_find_and_modify_opts_set_flags()</title>
10+
11+
<section id="synopsis">
12+
<title>Synopsis</title>
13+
<synopsis><code mime="text/x-csrc"><![CDATA[bool
14+
mongoc_find_and_modify_opts_set_flags (mongoc_find_and_modify_opts_t *opts,
15+
const mongoc_find_and_modify_flags_t flags);
16+
]]></code></synopsis>
17+
<note style="tip"><p>New in mongoc 1.3.0</p></note>
18+
</section>
19+
20+
<section id="parameters">
21+
<title>Parameters</title>
22+
<table>
23+
<tr><td><p>opts</p></td><td><p>A <code xref="mongoc_find_and_modify_opts_t">mongoc_find_and_modify_opts_t</code>.</p></td></tr>
24+
<tr><td><p>flags</p></td><td><p>.</p></td></tr>
25+
</table>
26+
</section>
27+
28+
<section id="description">
29+
<title>Description</title>
30+
<p>Adds one or more flags to the builder.</p>
31+
<table>
32+
<tr><td><p>MONGOC_FIND_AND_MODIFY_NONE</p></td><td><p>Default. Doesn't add anything to the builder.</p></td></tr>
33+
<tr><td><p>MONGOC_FIND_AND_MODIFY_REMOVE</p></td><td><p>Will instruct find_and_modify to remove the matching document.</p></td></tr>
34+
<tr><td><p>MONGOC_FIND_AND_MODIFY_UPSERT</p></td><td><p>Update the matching document or, if no document matches, insert the document.</p></td></tr>
35+
<tr><td><p>MONGOC_FIND_AND_MODIFY_RETURN_NEW</p></td><td><p>Return the resulting document.</p></td></tr>
36+
</table>
37+
</section>
38+
39+
40+
<section id="return">
41+
<title>Returns</title>
42+
<p>Returns true if it successfully added the option to the builder.</p>
43+
</section>
44+
45+
<section id="example">
46+
<title>Setting flags</title>
47+
<screen><code mime="text/x-csrc"><include parse="text" href="../examples/find_and_modify_with_opts/flags.c" xmlns="http://www.w3.org/2001/XInclude" /></code></screen>
48+
<p>Outputs:</p>
49+
<screen><code mime="text/x-csrc"><![CDATA[{
50+
"lastErrorObject": {
51+
"updatedExisting": false,
52+
"n": 1,
53+
"upserted": {
54+
"$oid": "56562a99d13e6d86239c7b00"
55+
}
56+
},
57+
"value": {
58+
"_id": {
59+
"$oid": "56562a99d13e6d86239c7b00"
60+
},
61+
"age": 34,
62+
"firstname": "Zlatan",
63+
"goals": 342,
64+
"lastname": "Ibrahimovic",
65+
"profession": "Football player",
66+
"position": "striker"
67+
},
68+
"ok": 1
69+
}]]></code></screen>
70+
</section>
71+
72+
73+
</page>

‎doc/mongoc_find_and_modify_opts_set_sort.page

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
<?xml version="1.0"?>
2+
<page xmlns="http://projectmallard.org/1.0/"
3+
type="topic"
4+
style="function"
5+
xmlns:api="http://projectmallard.org/experimental/api/"
6+
xmlns:ui="http://projectmallard.org/experimental/ui/"
7+
id="mongoc_find_and_modify_opts_set_sort">
8+
<info><link type="guide" xref="mongoc_find_and_modify_opts_t" group="function"/></info>
9+
<title>mongoc_find_and_modify_opts_set_sort()</title>
10+
11+
<section id="synopsis">
12+
<title>Synopsis</title>
13+
<synopsis><code mime="text/x-csrc"><![CDATA[bool
14+
mongoc_find_and_modify_opts_set_sort (mongoc_find_and_modify_opts_t *opts,
15+
const bson_t *sort);
16+
]]></code></synopsis>
17+
<note style="tip"><p>New in mongoc 1.3.0</p></note>
18+
</section>
19+
20+
<section id="parameters">
21+
<title>Parameters</title>
22+
<table>
23+
<tr><td><p>opts</p></td><td><p>A <code xref="mongoc_find_and_modify_opts_t">mongoc_find_and_modify_opts_t</code>.</p></td></tr>
24+
<tr><td><p>sort</p></td><td><p>Determines which document the operation modifies if the query selects multiple documents. findAndModify modifies the first document in the sort order specified by this argument.</p></td></tr>
25+
</table>
26+
</section>
27+
28+
<section id="description">
29+
<title>Description</title>
30+
<p>Adds sort argument to the builder.</p>
31+
</section>
32+
33+
34+
<section id="return">
35+
<title>Returns</title>
36+
<p>Returns true if it successfully added the option to the builder.</p>
37+
</section>
38+
39+
<section id="example">
40+
<title>Setting sort</title>
41+
<screen><code mime="text/x-csrc"><include parse="text" href="../examples/find_and_modify_with_opts/sort.c" xmlns="http://www.w3.org/2001/XInclude" /></code></screen>
42+
<p>Outputs:</p>
43+
<screen><code mime="text/x-csrc"><![CDATA[{
44+
"lastErrorObject": {
45+
"updatedExisting": true,
46+
"n": 1
47+
},
48+
"value": {
49+
"_id": {
50+
"$oid": "56562a99d13e6d86239c7b00"
51+
},
52+
"age": 35,
53+
"firstname": "Zlatan",
54+
"goals": 343,
55+
"lastname": "Ibrahimovic",
56+
"profession": "Football player",
57+
"position": "striker",
58+
"author": true
59+
},
60+
"ok": 1
61+
}]]></code></screen>
62+
</section>
63+
64+
65+
</page>

0 commit comments

Comments
 (0)