<!-- 
RSS generated by JIRA (9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66) at Wed Feb 07 21:13:40 UTC 2024

It is possible to restrict the fields that are returned in this document by specifying the 'field' parameter in your request.
For example, to request only the issue key and summary append 'field=key&field=summary' to the URL of your request.
-->
<rss version="0.92" >
<channel>
    <title>MongoDB Jira</title>
    <link>https://jira.mongodb.org</link>
    <description>This file is an XML representation of an issue</description>
    <language>en-us</language>    <build-info>
        <version>9.7.1</version>
        <build-number>970001</build-number>
        <build-date>13-04-2023</build-date>
    </build-info>


<item>
            <title>[CDRIVER-1937] bson_init_from_data() missing</title>
                <link>https://jira.mongodb.org/browse/CDRIVER-1937</link>
                <project id="10030" key="CDRIVER">C Driver</project>
                    <description>&lt;p&gt;There is no &lt;tt&gt;bson_init_from_data()&lt;/tt&gt; counterpart for &lt;tt&gt;bson_new_from_data()&lt;/tt&gt;. Please note, however, that there is &lt;tt&gt;bson_init_from_json()&lt;/tt&gt; for its &lt;tt&gt;bson_new_from_json()&lt;/tt&gt; sibling in case of JSON.&lt;/p&gt;

&lt;p&gt;In other words, there is no effective way to initialize a pre-allocated &lt;tt&gt;bson_t&lt;/tt&gt; from a raw data buffer similar to &lt;tt&gt;bson_init_from_json()&lt;/tt&gt;. The only feasible way now is to use a temporary which is sloppy:&lt;/p&gt;

&lt;p/&gt;
&lt;div id=&quot;syntaxplugin&quot; class=&quot;syntaxplugin&quot; style=&quot;border: 1px dashed #bbb; border-radius: 5px !important; overflow: auto; max-height: 30em;&quot;&gt;
&lt;table cellspacing=&quot;0&quot; cellpadding=&quot;0&quot; border=&quot;0&quot; width=&quot;100%&quot; style=&quot;font-size: 1em; line-height: 1.4em !important; font-weight: normal; font-style: normal; color: black;&quot;&gt;
		&lt;tbody &gt;
				&lt;tr id=&quot;syntaxplugin_code_and_gutter&quot;&gt;
						&lt;td  style=&quot; line-height: 1.4em !important; padding: 0em; vertical-align: top;&quot;&gt;
					&lt;pre style=&quot;font-size: 1em; margin: 0 10px;  margin-top: 10px;   width: auto; padding: 0;&quot;&gt;&lt;span style=&quot;color: black; font-family: &apos;Consolas&apos;, &apos;Bitstream Vera Sans Mono&apos;, &apos;Courier New&apos;, Courier, monospace !important;&quot;&gt;bson_t bson;&lt;/span&gt;&lt;/pre&gt;
			&lt;/td&gt;
		&lt;/tr&gt;
				&lt;tr id=&quot;syntaxplugin_code_and_gutter&quot;&gt;
						&lt;td  style=&quot; line-height: 1.4em !important; padding: 0em; vertical-align: top;&quot;&gt;
					&lt;pre style=&quot;font-size: 1em; margin: 0 10px;   margin-bottom: 10px;  width: auto; padding: 0;&quot;&gt;&lt;span style=&quot;color: black; font-family: &apos;Consolas&apos;, &apos;Bitstream Vera Sans Mono&apos;, &apos;Courier New&apos;, Courier, monospace !important;&quot;&gt;bson_copy_to(bson_new_from_data(data, length), &amp;amp;bson);&lt;/span&gt;&lt;/pre&gt;
			&lt;/td&gt;
		&lt;/tr&gt;
			&lt;/tbody&gt;
&lt;/table&gt;
&lt;/div&gt;
&lt;p/&gt;</description>
                <environment></environment>
        <key id="334282">CDRIVER-1937</key>
            <summary>bson_init_from_data() missing</summary>
                <type id="4" iconUrl="https://jira.mongodb.org/secure/viewavatar?size=xsmall&amp;avatarId=14710&amp;avatarType=issuetype">Improvement</type>
                                            <priority id="4" iconUrl="https://jira.mongodb.org/images/icons/priorities/minor.svg">Minor - P4</priority>
                        <status id="6" iconUrl="https://jira.mongodb.org/images/icons/statuses/closed.png" description="The issue is considered finished, the resolution is correct. Issues which are closed can be reopened.">Closed</status>
                    <statusCategory id="3" key="done" colorName="success"/>
                                    <resolution id="9">Done</resolution>
                                        <assignee username="jesse@mongodb.com">A. Jesse Jiryu Davis</assignee>
                                    <reporter username="neoxic">Arseny Vakhrushev</reporter>
                        <labels>
                    </labels>
                <created>Fri, 25 Nov 2016 21:54:53 +0000</created>
                <updated>Thu, 26 Jan 2017 23:48:10 +0000</updated>
                            <resolved>Thu, 26 Jan 2017 23:48:10 +0000</resolved>
                                                    <fixVersion>1.6.0</fixVersion>
                                    <component>libbson</component>
                                        <votes>0</votes>
                                    <watches>3</watches>
                                                                                                                <comments>
                            <comment id="1486412" author="bjori" created="Thu, 26 Jan 2017 23:48:10 +0000"  >&lt;p&gt;The docs have been updated to improve discoverability of init/new functions&lt;/p&gt;</comment>
                            <comment id="1479897" author="neoxic" created="Wed, 18 Jan 2017 23:43:20 +0000"  >&lt;p&gt;Right on! &lt;img class=&quot;emoticon&quot; src=&quot;https://jira.mongodb.org/images/icons/emoticons/wink.png&quot; height=&quot;16&quot; width=&quot;16&quot; align=&quot;absmiddle&quot; alt=&quot;&quot; border=&quot;0&quot;/&gt; I&apos;ll leave the opportunity to create it to someone else if it&apos;s worth doing.&lt;/p&gt;</comment>
                            <comment id="1479890" author="bjori" created="Wed, 18 Jan 2017 23:31:43 +0000"  >&lt;p&gt;that sounds like a conversation for a different ticket &lt;img class=&quot;emoticon&quot; src=&quot;https://jira.mongodb.org/images/icons/emoticons/smile.png&quot; height=&quot;16&quot; width=&quot;16&quot; align=&quot;absmiddle&quot; alt=&quot;&quot; border=&quot;0&quot;/&gt;&lt;/p&gt;</comment>
                            <comment id="1473169" author="neoxic" created="Mon, 9 Jan 2017 23:34:26 +0000"  >&lt;p&gt;Your cooperation is much appreciated, Hannes! Many thanks!&lt;/p&gt;

&lt;blockquote&gt;&lt;p&gt;It was however a mistake to add those convenience functions. See for example &lt;a href=&quot;https://jira.mongodb.org/browse/CDRIVER-1916&quot; title=&quot;bson_iter_init_find() and bson_iter_init_find_case() should return false only when iterator is successfully exhausted and key not found&quot; class=&quot;issue-link&quot; data-issue-key=&quot;CDRIVER-1916&quot;&gt;&lt;del&gt;CDRIVER-1916&lt;/del&gt;&lt;/a&gt;.&lt;/p&gt;&lt;/blockquote&gt;

&lt;p&gt;Oh, no, that&apos;s a completely different problem in libbson. Wrappers have nothing to do with it as it is a separate API design flaw. For example, how come &lt;tt&gt;bson_iter_init()&lt;/tt&gt; has a return value in the first place? If it didn&apos;t, there wouldn&apos;t be a problem like &lt;a href=&quot;https://jira.mongodb.org/browse/CDRIVER-1916&quot; title=&quot;bson_iter_init_find() and bson_iter_init_find_case() should return false only when iterator is successfully exhausted and key not found&quot; class=&quot;issue-link&quot; data-issue-key=&quot;CDRIVER-1916&quot;&gt;&lt;del&gt;CDRIVER-1916&lt;/del&gt;&lt;/a&gt; at all.&lt;/p&gt;

&lt;p&gt;Consider this, &lt;tt&gt;bson_iter_init()&lt;/tt&gt; returns a boolean when it clearly should&apos;t whereas some other calls will yell in &lt;tt&gt;stderr&lt;/tt&gt; on errors instead of returning them. How is that? &lt;tt&gt;bson_iter_init()&lt;/tt&gt; should probably silently initialize an iterator much like &lt;tt&gt;bson_init()&lt;/tt&gt;. If the underlying data is invalid, there are two options:&lt;br/&gt;
  1) API unambiguously requires that iterator functions be called on valid data, or undefined behaviour ensues; or&lt;br/&gt;
  2) The subsequent &lt;tt&gt;bson_iter_next()&lt;/tt&gt; call returns false.&lt;/p&gt;

&lt;p&gt;If you ask me, I think it&apos;s a sloppy road to try to check for data integrity in each API call which does not solve the problem anyway. But that is the primary reason why so many API calls have return values. Leave alone the fact the user&apos;s manual doesn&apos;t bother to explain what ...&lt;/p&gt;

&lt;blockquote&gt;&lt;p&gt;&quot;true if the operation was applied successfully, otherwise false and bson should be discarded&quot;&lt;/p&gt;&lt;/blockquote&gt;

&lt;p&gt;... even means. In what cases can an operation fail and what does a &quot;failure&quot; exactly mean? What party - caller or callee - is responsible for that? What can be done to prevent it? For a user like me, this looks vague and ambiguous. But the real problem here is that I am left with no other choice but to either propagate these conditions blindly or ignore them altogether thus breaking the contract and potentially multiplying the suffering even more. In both ways, the higher level user is left to pay the bill they will never understand.&lt;/p&gt;</comment>
                            <comment id="1471377" author="bjori" created="Fri, 6 Jan 2017 18:33:03 +0000"  >&lt;p&gt;I agree that these oneliner helper functions like &lt;tt&gt;bson_iter_init_find&lt;/tt&gt; are very convenient, and I&apos;m sure &lt;tt&gt;bson_init_from_data&lt;/tt&gt; could also be equally convenient.&lt;/p&gt;

&lt;p&gt;It was however a mistake to add those convenience functions. See for example &lt;a href=&quot;https://jira.mongodb.org/browse/CDRIVER-1916&quot; title=&quot;bson_iter_init_find() and bson_iter_init_find_case() should return false only when iterator is successfully exhausted and key not found&quot; class=&quot;issue-link&quot; data-issue-key=&quot;CDRIVER-1916&quot;&gt;&lt;del&gt;CDRIVER-1916&lt;/del&gt;&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;Rather then adding functions for all mutations of symmetric function names, I think we should rather extend the docs to point out the other ways to achieve the same goal instead.&lt;/p&gt;

&lt;p&gt;To that end, I am going to crosslink all the &lt;tt&gt;bson_init*&lt;/tt&gt; and &lt;tt&gt;bson_new*&lt;/tt&gt; functions, and also add link to &lt;tt&gt;bson_concat&lt;/tt&gt; and then close this ticket.&lt;/p&gt;</comment>
                            <comment id="1470928" author="neoxic" created="Fri, 6 Jan 2017 04:45:15 +0000"  >&lt;p&gt;Thanks for your reply, Hannes! The purpose of this report is to show that there seems to be a little inconsistency (imbalance) in the current API in regards to the above.&lt;/p&gt;

&lt;p&gt;If a user (someone, not me) sees two API calls, namely &lt;tt&gt;bson_new_from_json()&lt;/tt&gt; and &lt;tt&gt;bson_new_from_data()&lt;/tt&gt;, most definitely they will anticipate to see two symmetrical calls, namely &lt;tt&gt;bson_init_from_json()&lt;/tt&gt; and &lt;tt&gt;bson_init_from_data()&lt;/tt&gt;. But the latter is just not there...&lt;/p&gt;

&lt;p&gt;One could care less. One could use &lt;tt&gt;bson_concat()&lt;/tt&gt; if you say it&apos;s efficient. One could use &lt;tt&gt;bson_copy()&lt;/tt&gt; if they didn&apos;t care about performance. The question is not about how to attain the goal. It&apos;s surely attainable. The question is if this way is &lt;b&gt;visible&lt;/b&gt; and &lt;b&gt;simple&lt;/b&gt; enough for the user.&lt;/p&gt;

&lt;p&gt;I see other similar inconsistencies throughout the API. For example, there&apos;s &lt;tt&gt;bson_iter_init_find()&lt;/tt&gt; which is just a wrapper around &lt;tt&gt;(bson_iter_init() &amp;amp;&amp;amp; bson_iter_find())&lt;/tt&gt; along with its sibling &lt;tt&gt;bson_iter_init_find_case()&lt;/tt&gt; to counter &lt;tt&gt;bson_iter_find_case()&lt;/tt&gt;. These guys are surely convenient although obviously redundant. And I, as a user, appreciate that someone made an effort and included them into the API.&lt;/p&gt;

&lt;p&gt;But... for some reason, there&apos;s no &lt;tt&gt;bson_iter_init_find_descendant()&lt;/tt&gt; for its &lt;tt&gt;bson_iter_find_descendant()&lt;/tt&gt; sibling. Why?&lt;/p&gt;

&lt;p&gt;Someone took care and created a simple one-liner named &lt;tt&gt;bson_iter_init_find()&lt;/tt&gt;. I fail to see why it&apos;s impossible to do the same for a hypothetical &lt;tt&gt;bson_init_from_data()&lt;/tt&gt; even if it would be just a one-liner like &lt;tt&gt;(bson_init() &amp;amp;&amp;amp; bson_concat())&lt;/tt&gt; (or whatever your pick is).&lt;/p&gt;

&lt;p&gt;There seems to be lack of consistent approach to these things in general. And I&apos;m just pointing this out. That&apos;s all. You don&apos;t have to defend yourself. Your project - your rules. These are just my five cents...&lt;img class=&quot;emoticon&quot; src=&quot;https://jira.mongodb.org/images/icons/emoticons/biggrin.png&quot; height=&quot;16&quot; width=&quot;16&quot; align=&quot;absmiddle&quot; alt=&quot;&quot; border=&quot;0&quot;/&gt;&lt;/p&gt;</comment>
                            <comment id="1470656" author="bjori" created="Thu, 5 Jan 2017 23:37:11 +0000"  >&lt;p&gt;I think maybe &lt;tt&gt;&lt;a href=&quot;http://mongoc.org/libbson/current/bson_concat.html&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;bson_concat&lt;/a&gt;&lt;/tt&gt; does then exactly what you want?&lt;/p&gt;

&lt;p&gt;The question isn&apos;t how technically difficult it is to add another function that does something, or add another function to complete some homebrewed naming schema for all mutations of its variations, instead, the questions is if we really want to encourage doing something that is better achieved in other ways &amp;#8211; or maybe not at all.&lt;/p&gt;

&lt;p&gt;If you have heap allocated &lt;tt&gt;bson_t&lt;/tt&gt; you can initialize it with &lt;tt&gt;BSON_INITIALIZER&lt;/tt&gt; and simply concatenate existing &lt;tt&gt;bson_t&lt;/tt&gt; to it which I believe might solve your problem if &lt;tt&gt;bson_init_static&lt;/tt&gt; does not suite your case.&lt;/p&gt;</comment>
                            <comment id="1454340" author="neoxic" created="Fri, 9 Dec 2016 21:28:00 +0000"  >&lt;blockquote&gt;&lt;p&gt;I don&apos;t think you would want a bson_init_from_data which would copy the data into a bson_t?&lt;/p&gt;&lt;/blockquote&gt;

&lt;p&gt;This is exactly what I want actually. Please see the workaround above. I have an uninitialized &lt;tt&gt;bson_t&lt;/tt&gt; allocated on the heap, and I want to initialize it with data that already exists in another &lt;tt&gt;bson_t&lt;/tt&gt; object, i.e. effectively copy the document &lt;b&gt;by value&lt;/b&gt;.&lt;/p&gt;

&lt;blockquote&gt;&lt;p&gt;Have you tried using bson_init_static for your usecase?&lt;/p&gt;&lt;/blockquote&gt;

&lt;p&gt;According to the &lt;a href=&quot;http://mongoc.org/libbson/current/bson_init_static.html&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;manual&lt;/a&gt;, this call is not intended for copying purposes:&lt;/p&gt;

&lt;blockquote&gt;&lt;p&gt;&quot;... function shall initialize a read-only bson_t on the stack using the data provided. No copies of the data will be made and therefore must remain valid for the lifetime of the bson_t.&quot;&lt;/p&gt;&lt;/blockquote&gt;

&lt;p&gt;The above is more like creating a reference for the lifetime of the source object. No doubt, this can be useful sometimes, but it has nothing to do with my case when a newly created &lt;tt&gt;bson_t&lt;/tt&gt; is not read-only, nor can it be guaranteed that the source will remain valid for its lifetime.&lt;/p&gt;

&lt;p&gt;Again, there are ways to initialize an &lt;b&gt;already&lt;/b&gt; allocated, but &lt;b&gt;&lt;font color=&quot;red&quot;&gt;uninitialized&lt;/font&gt;&lt;/b&gt; &lt;tt&gt;bson_t&lt;/tt&gt; with:&lt;br/&gt;
1. Nothing - &lt;tt&gt;bson_init()&lt;/tt&gt;&lt;br/&gt;
2. JSON - &lt;tt&gt;bson_init_from_json()&lt;/tt&gt;&lt;/p&gt;

&lt;p&gt;There is no way to initialize it with &lt;tt&gt;data&lt;/tt&gt; (i.e. make an effective copy by value).&lt;/p&gt;

&lt;p&gt;As for &lt;b&gt;allocate-and-initialize&lt;/b&gt;, a &lt;tt&gt;bson_t&lt;/tt&gt; can be initialized with:&lt;br/&gt;
1. Nothing - &lt;tt&gt;bson_new()&lt;/tt&gt;&lt;br/&gt;
2. JSON - &lt;tt&gt;bson_new_from_json()&lt;/tt&gt;&lt;br/&gt;
3. Data - &lt;tt&gt;bson_new_from_data()&lt;/tt&gt;&lt;/p&gt;

&lt;blockquote&gt;&lt;p&gt;The difference to bson_init_from_json though is because json is entirely different data it must allocate new space for the conversion.&lt;/p&gt;&lt;/blockquote&gt;

&lt;p&gt;I really can&apos;t see how JSON itself is related to this issue because it should be fairly simple in a hypothetical &lt;tt&gt;bson_init_from_data()&lt;/tt&gt; to leave the allocation of a &lt;tt&gt;bson_t&lt;/tt&gt; structure to the user with the remaining code identical to &lt;tt&gt;bson_new_from_data()&lt;/tt&gt;.&lt;/p&gt;</comment>
                            <comment id="1454160" author="bjori" created="Fri, 9 Dec 2016 19:32:10 +0000"  >&lt;p&gt;&lt;a href=&quot;http://mongoc.org/libbson/current/bson_init_static.html&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;bson_init_static&lt;/a&gt; is meant to initialize &lt;tt&gt;bson_t&lt;/tt&gt; from pre-allocated data (without taking ownership of the data).&lt;/p&gt;

&lt;p&gt;The difference to &lt;tt&gt;bson_init_from_json&lt;/tt&gt; though is because json is entirely different data it must allocate new space for the conversion.&lt;br/&gt;
I don&apos;t think you would want a &lt;tt&gt;bson_init_from_data&lt;/tt&gt; which would copy the data into a bson_t?&lt;/p&gt;

&lt;p&gt;Have you tried using &lt;tt&gt;bson_init_static&lt;/tt&gt; for your usecase?&lt;/p&gt;</comment>
                            <comment id="1442515" author="neoxic" created="Fri, 25 Nov 2016 22:21:05 +0000"  >&lt;p&gt;Sorry, the example is also leaky. It should in fact be something like this:&lt;/p&gt;
&lt;p/&gt;
&lt;div id=&quot;syntaxplugin&quot; class=&quot;syntaxplugin&quot; style=&quot;border: 1px dashed #bbb; border-radius: 5px !important; overflow: auto; max-height: 30em;&quot;&gt;
&lt;table cellspacing=&quot;0&quot; cellpadding=&quot;0&quot; border=&quot;0&quot; width=&quot;100%&quot; style=&quot;font-size: 1em; line-height: 1.4em !important; font-weight: normal; font-style: normal; color: black;&quot;&gt;
		&lt;tbody &gt;
				&lt;tr id=&quot;syntaxplugin_code_and_gutter&quot;&gt;
						&lt;td  style=&quot; line-height: 1.4em !important; padding: 0em; vertical-align: top;&quot;&gt;
					&lt;pre style=&quot;font-size: 1em; margin: 0 10px;  margin-top: 10px;   width: auto; padding: 0;&quot;&gt;&lt;span style=&quot;color: black; font-family: &apos;Consolas&apos;, &apos;Bitstream Vera Sans Mono&apos;, &apos;Courier New&apos;, Courier, monospace !important;&quot;&gt;bson_t bson, *tmp = bson_new_from_data(data, length);&lt;/span&gt;&lt;/pre&gt;
			&lt;/td&gt;
		&lt;/tr&gt;
				&lt;tr id=&quot;syntaxplugin_code_and_gutter&quot;&gt;
						&lt;td  style=&quot; line-height: 1.4em !important; padding: 0em; vertical-align: top;&quot;&gt;
					&lt;pre style=&quot;font-size: 1em; margin: 0 10px;   width: auto; padding: 0;&quot;&gt;&lt;span style=&quot;color: black; font-family: &apos;Consolas&apos;, &apos;Bitstream Vera Sans Mono&apos;, &apos;Courier New&apos;, Courier, monospace !important;&quot;&gt;bson_copy_to(tmp, &amp;amp;bson);&lt;/span&gt;&lt;/pre&gt;
			&lt;/td&gt;
		&lt;/tr&gt;
				&lt;tr id=&quot;syntaxplugin_code_and_gutter&quot;&gt;
						&lt;td  style=&quot; line-height: 1.4em !important; padding: 0em; vertical-align: top;&quot;&gt;
					&lt;pre style=&quot;font-size: 1em; margin: 0 10px;   margin-bottom: 10px;  width: auto; padding: 0;&quot;&gt;&lt;span style=&quot;color: black; font-family: &apos;Consolas&apos;, &apos;Bitstream Vera Sans Mono&apos;, &apos;Courier New&apos;, Courier, monospace !important;&quot;&gt;bson_destroy(tmp);&lt;/span&gt;&lt;/pre&gt;
			&lt;/td&gt;
		&lt;/tr&gt;
			&lt;/tbody&gt;
&lt;/table&gt;
&lt;/div&gt;
&lt;p/&gt;</comment>
                    </comments>
                    <attachments>
                    </attachments>
                <subtasks>
                    </subtasks>
                <customfields>
                                                                                                                                                                                                                                                                                                                                                                    <customfield id="customfield_15850" key="com.atlassian.jira.plugins.jira-development-integration-plugin:devsummary">
                        <customfieldname>Development</customfieldname>
                        <customfieldvalues>
                            
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            <customfield id="customfield_12550" key="com.pyxis.greenhopper.jira:gh-lexo-rank">
                        <customfieldname>Rank</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>2|hrb91r:</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_10558" key="com.pyxis.greenhopper.jira:gh-global-rank">
                        <customfieldname>Rank (Obsolete)</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>9223372036854775807</customfieldvalue>
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                    <customfield id="customfield_10557" key="com.pyxis.greenhopper.jira:gh-sprint">
                        <customfieldname>Sprint</customfieldname>
                        <customfieldvalues>
                                <customfieldvalue id="1481">C Driver 2017 1 - Jan 20, 2017</customfieldvalue>
    <customfieldvalue id="1558">C Driver 2017 2 - Feb 10, 2018</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            </customfields>
    </item>
</channel>
</rss>