documentation for valueOf() and toString() (DOCS-563)

[DOCS-584] Release notes for 2.2 should mention breaking change: ObjectId().valueOf() and ObjectId().toString() have reversed meanings Created: 07/Oct/12  Updated: 30/Oct/23  Resolved: 18/Oct/12

Status: Closed
Project: Documentation
Component/s: Server
Affects Version/s: None
Fix Version/s: Server_Docs_20231030

Type: Sub-task Priority: Minor - P4
Reporter: Tad Marshall Assignee: Kay Kim (Inactive)
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
related to SERVER-5439 Add ObjectId.toHexString() Closed
related to DOCS-586 Document "str" property of ObjectId()... Closed
is related to SERVER-7055 ObjectId to String type conversion di... Closed
is related to DOCS-563 documentation for valueOf() and toStr... Closed
is related to SERVER-2684 special types in shell (e.g. Timestam... Closed
is related to SERVER-6986 ObjectId#toString and ObjectId#valueOf Closed
Participants:
Days since reply: 11 years, 17 weeks, 6 days ago

 Description   

We changed the result returned by the valueOf() and toString() methods of ObjectId() in 2.1.0 and later compared to the 2.0 series.

Version 2.0

MongoDB shell version: 2.0.8-rc0-pre-
connecting to: test
> var o = new ObjectId()
> o
ObjectId("507172c510b40cc18add2475")
> o.str
507172c510b40cc18add2475
> o.valueOf()
ObjectId("507172c510b40cc18add2475")
> o.toString()
507172c510b40cc18add2475
> o.tojson()
ObjectId("507172c510b40cc18add2475")
> typeof o
object
> typeof o.str
string
> typeof o.valueOf()
object
> typeof o.toString()
string
> typeof o.tojson()
string
> o.valueOf
function valueOf() {
    [native code]
}
> o.toString
function toString() {
    [native code]
}
> o.tojson
function () {
    return "ObjectId(\"" + this.str + "\")";
}
>

Version 2.1, 2.2 and higher

MongoDB shell version: 2.3.0-pre-
connecting to: test
> var o = new ObjectId()
> o
ObjectId("5071731713a0d4c2ef2a2c02")
> o.str
5071731713a0d4c2ef2a2c02
> o.valueOf()
5071731713a0d4c2ef2a2c02
> o.toString()
ObjectId("5071731713a0d4c2ef2a2c02")
> o.tojson()
ObjectId("5071731713a0d4c2ef2a2c02")
> typeof o
object
> typeof o.str
string
> typeof o.valueOf()
string
> typeof o.toString()
string
> typeof o.tojson()
string
> o.valueOf
function () {
    return this.str;
}
> o.toString
function () {
    return "ObjectId(" + tojson(this.str) + ")";
}
> o.tojson
function () {
    return this.toString();
}
>

The short version is that any code using ObjectId().toValue() or ObjectId().toString() will break when moving from version 2.0 to version 2.2.

If compatibility between versions 2.0 and 2.2 is required, use ObjectId().str, which is a string property holding the hex string value in both versions, or use ObjectId().tojson(), which returns a string containing 'ObjectId("<hex string value>")' in both versions.

Alternatively, if changing affected code is not feasible, it is possible to revert the methods in 2.2 to their 2.0 meanings by changing ObjectId.prototype:

revertObjectIdMethods.js

// Revert ObjectId().toString(), .valueOf() and .tojson() to their version 2.0 behaviors
//
ObjectId.prototype.toString = function(){
    return this.str;
}
ObjectId.prototype.valueOf = function(){
    return "ObjectId(" + tojson(this.str) + ")";
}
ObjectId.prototype.tojson = function(){
    return "ObjectId(" + tojson(this.str) + ")";
}

Example of using revertObjectIdMethods.js

MongoDB shell version: 2.3.0-pre-
connecting to: test
> var o = new ObjectId()
> o.valueOf()
5071ad1b4ed39323ce5d275f
> o.toString()
ObjectId("5071ad1b4ed39323ce5d275f")
> o.tojson()
ObjectId("5071ad1b4ed39323ce5d275f")
> load("revertObjectIdMethods.js")
> o.valueOf()
ObjectId("5071ad1b4ed39323ce5d275f")
> o.toString()
5071ad1b4ed39323ce5d275f
> o.tojson()
ObjectId("5071ad1b4ed39323ce5d275f")
>

See linked tickets for more information.



 Comments   
Comment by auto [ 18/Oct/12 ]

Author:

{u'date': u'2012-10-18T12:14:05-07:00', u'email': u'kay.kim@10gen.com', u'name': u'kay'}

Message: DOCS-584 ObjectId valueOf and toString release notes
Branch: master
https://github.com/mongodb/docs/commit/4da33114d0aaab99115cab55510005ee841d9fee

Generated at Thu Feb 08 07:39:01 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.