211

This is perhaps not a perfectly suitable forum for this question, but let me give it a shot, at the risk of being moved away.

There are several references for the C++ standard library, including the invaluable ISO standard, MSDN, IBM, cppreference, and cplusplus. Personally, when writing C++ I need a reference that has quick random access, short load times and usage examples, and I've been finding cplusplus.com pretty useful. However, I've been hearing negative opinions about that website frequently here on SO, so I would like to get specific:

What are the errors, misconceptions or bad pieces of advice given by cplusplus.com? What are the risks of using it to make coding decisions?

Let me add this point: I want to be able to answer questions here on SO with accurate quotes of the standard, and thus I would like to post immediately-usable links, and cplusplus.com would have been my choice site were it not for this issue.

Mark Amery
  • 110,735
  • 57
  • 354
  • 402
Kerrek SB
  • 428,875
  • 83
  • 813
  • 1,025
  • 1
    Can you make your question more specific. Where did you find negative opinions? For part of it? – balki Jun 29 '11 at 11:43
  • 66
    Why the downvotes? This is a perfectly valid question. If you need a reference, you want a trusted source. I also heard complaints against cplusplus.com, where I can get a quick reference for the standard library and as such, this is interesting. – Xeo Jun 29 '11 at 11:45
  • 3
    @Balki: Feedback is scattered about, but frequently when someone cites cplusplus.com as a reference for some library feature or another, someone else will comment on the bad quality of that site as a reference. Sometimes even the author themselves will preface references to the site with a warning. I just want to avoid using a broken reference, especially since I like to be able to answer other questions with authoritative quotes! – Kerrek SB Jun 29 '11 at 11:45
  • 3
    This question would probably attract more personal opinion than actual answers. – Ólafur Waage Jun 29 '11 at 11:48
  • 49
    @Olafur: I don't want opinion, I want concrete listings of mistakes on that site. If there aren't any, I want to be able to use this question to dispel future criticism. – Kerrek SB Jun 29 '11 at 11:49
  • 4
    @Ólafur Waage: maybe. But perfectly objective points can be made about the accuracy / truthfulness of the contents of that website. – Daniel Sloof Jun 29 '11 at 11:50
  • 3
    @Kerrek: the site is not authoritative, so you cannot take its content at face value, however people are encouraged to report the error spotted, so I would guess (and hope) that any list of actual errors would be futile as it would lead to their correction. – Matthieu M. Jun 29 '11 at 11:51
  • 2
    Showing some errors as expample can give a good feeling if it should be used in future or not. Are there some fundamental mistakes or only acceptable minor typings?! IMHO this is a valid question. Ok this is not a forum, but this is a place of knowledge and this question belongs to it. – Markus Jun 29 '11 at 11:56
  • While there is certainly erroneous information on cplusplus.com (which encyclopedia gets it right all the time?), I think it is fair to say that there is nothing inherently *wrong* with it. It's a fine and reliable source of information. It loads quickly and provides excellent coverage of the C++ standard libraries. – Alexander Gessler Jun 29 '11 at 12:02
  • @Mattieu: Of course, nothing but the standard is authoritative. But during my occasional sampling I've always found the site to be accurate. My question is expressly what's *wrong* with it. An exact replica of the standard would be totally fine. – Kerrek SB Jun 29 '11 at 12:02
  • @DeadMG: I meant "forum" in its original meaning, not the internet tech term. Sorry, probably a poor choice of words with hindsight. – Kerrek SB Jun 29 '11 at 12:11
  • 3
    I've reported errors on that site before, and they've been fixed pretty quickly. Perhaps I've gotten lucky in that regard, but this has serious potential to quickly become q series of out of date answers. – Dennis Zickefoose Jun 29 '11 at 12:34
  • "accurate quotes of the standard" - cplusplus.com is certainly inadequate for this specialized purpose, since it doesn't quote the standard, it paraphrases it. – Steve Jessop Jun 29 '11 at 12:34
  • 2
    This may or may not be strictly on-topic; I can't really decide. However one thing is for sure: this is _important_ ground to cover. So let's keep it and see where it takes us. – Lightness Races in Orbit Jun 29 '11 at 13:01
  • 14
    We're already on page one for "cplusplus.com" on Google. It's impressive how quickly SO questions climb the search rankings. – Lightness Races in Orbit Jun 29 '11 at 13:53
  • @Kerrek: Asking for a full list of all typos, bugs and errors throughout the entire reference isn't really appropriate for SO, and is a non-starter anyway. Best we can do is give some examples and a more rounded idea of why it's a poor resource to recommend to someone. – Lightness Races in Orbit Jun 29 '11 at 15:01
  • @Tomalak: I'm pretty happy with the answers that are turning up. A selection of a couple of choice errors and misleading information is a very good start. – Kerrek SB Jun 29 '11 at 15:03
  • 4
    @David: I don't want to make cplusplus a better site, and I'm not whining. I just want robust reasons to be wary of the site, which I would otherwise have treated as a reliable resource and used in arguments. Since the site is one of my (and many other people's) main tools when programming, this is a practical and straight-forward programming-related question. – Kerrek SB Jun 29 '11 at 17:09
  • @David: I think the point is to provide evidence for (or against, but the ship has sailed on that) the common claim, "cplusplus.com is not very accurate". It's "obvious" if you often use the site as a quick reference, but not necessarily easy to demonstrate clearly to others who assume cplusplus.com is accurate or authoritative. However, questions about programming resources, or anything other than "how do I do X in Y environment" are getting less popular around here, at least with the 5 people needed to close them, so you may be right that assessing C++ resources is no longer "constructive". – Steve Jessop Jun 29 '11 at 18:42
  • 5
    I think it's fair--given how highly this question ranks on searches for "cplusplus"--to note that, since this question was asked, a number of corrections have been made to cplusplus.com. In fact, the top three answers that point out mistakes are no longer true. – Mark H Jun 02 '16 at 13:11
  • The reason why I switched from cplusplus.com to cppreference.com was because the former had extremely long load times – Post Self Aug 10 '17 at 08:25
  • [`str.append(5,0x2E);` example](http://www.cplusplus.com/reference/string/string/append/) doesn't compile – Rufus Oct 02 '18 at 09:52
  • https://cppreference.com/ is simply a better reference site. It's more complete and contain fewer errors. – Jesper Juhl Jun 29 '19 at 13:56

6 Answers6

73

Edit: Documentation for std::remove has been fixed since this answer was written. Same thing applies to list::remove.

Let me give you an example to show you how cpluscplus.com can get it wrong.

Consider std::remove function from <algorithm>.

The fact is thatstd::remove doesn't remove the item from the container. Its because std::remove works with a pair of iterators only and does not know anything about the container which actually contains the items. In fact, it's not possible for std::remove to know the underlying container, because there is no way it can go from a pair of iterators to discover about the container to which the iterators belong. So std::remove doesn't really remove the items, simply because it cannot. The only way to actually remove an item from a container is to invoke a member function on that container.

So if you want to remove the items, then use Erase-Remove Idiom:

 v.erase(std::remove(v.begin(), v.end(), 10), v.end());

But cplusplus.com gives incorrect information about std::remove. It says

Notice that this function does not alter the elements past the new end, which keep their old values and are still accessible.

which isn't correct. The iterator in the range [new_end, old_end) is still dereferenceable, but that does NOT mean that they keep the old values and are still accessible. They are unspecified.

Similarly, cplusplus.com gives incorrect information about list::remove as well. It says,

Notice that a global algorithm function, remove, exists with a similar behavior but operating between two iterators.

which is completely wrong. The global remove namely std::remove is not similar to list::remove, as we saw that the former does NOT really remove the items from the container because it cannot, whereas the latter (the member function) really does remove the items because it can.

This answer is copied from my another answer in the following topic, with little modification:

Note: Since I came across this recently when I was replying in the above topic, I remember it. There are many errors which I've come across over the last two years, which I don't remember. I might add few more later, if I come across again.

Community
  • 1
  • 1
Nawaz
  • 327,095
  • 105
  • 629
  • 812
  • 1
    +1: are there a lot more of those incorrect statements on this site? – Klaim Jun 29 '11 at 12:00
  • @Klaim: Yes. But this I came across recently, so I remember. – Nawaz Jun 29 '11 at 12:01
  • It says 'similar' behaviour and indeed, `list::remove` and `std::remove` have similar behaviour. That the latter can't remove elements from the sequence is obvious and needs no further notes, even though I agree that it can confuse beginners. – Alexander Gessler Jun 29 '11 at 12:05
  • 4
    @Alexander: `list::remove` does remove the elements from the container. But `std::remove` does NOT remove the elements from the container. I **cannot** say their behavior are "similar". – Nawaz Jun 29 '11 at 12:08
  • 3
    Nice catch! That's a very good example of the things I'm looking for. – Kerrek SB Jun 29 '11 at 12:14
  • @Nawaz I think he understood that, and yes they have "similar" behaviour, for the exact behaviour you have to look into `std::remove`. – Christian Rau Jun 29 '11 at 12:16
  • 3
    "Similar" is debateable, since it's a matter of opinion whether two different operations are similar or not. It's also debateable whether cplusplus.com should be offering opinion disguised as documentation. But anyway, "keep their old values" is an unforgiveable error, it just shows that the cplusplus description wasn't based on the standard. – Steve Jessop Jun 29 '11 at 12:27
  • Where by "unforgiveable" of course I mean "unless it's fixed". I'm not claiming I'd hold a grudge indefinitely... – Steve Jessop Jun 29 '11 at 12:40
  • Regarding 'similar': I would call the behavior of std::remove and std::list::remove 'similar'. Certainly the standards committee thought the operations were 'similar' enough so as to have the same name. The problem with the cplusplus explanation boils down to its erroneously giving specificity to the unspecified contents of [new_last, last). – David Hammen Jun 29 '11 at 13:20
  • @Steve: It would render me suspicious of general quality indefinitely. – Lightness Races in Orbit Jun 29 '11 at 13:57
  • 5
    @Steve: You said `"Similar" is debateable`. If the word `similar` is debatable, then it very much tells that this word isn't the correct word and should be avoided when explaining the behavior of `std::remove` and `list::remove`, because an *explanation* should be clear as much as possible, it should not require another explanation. – Nawaz Jun 29 '11 at 17:42
40

I'm going to offer an opinion slightly to the contrary. There is lots of good information on cplusplus.com. Pick at it to death, and yes, of course it has its problems, but what site doesn't? Certainly not this site. People who live in glass houses shouldn't throw stones. There is a lot of misinformation here, too. There are accepted answers that are flat-out wrong, downvoted answers (some negative!) that are spot-on correct.

One issue with cplusplus.com is is that it is a closed site; the same goes for most the other reference sites mentioned. This goes against the grain of a community-developed site such as Stack Overflow. Acquiring the ability to make trusted edits doesn't take all that long, and even the newest of newbies can easily make suggestions for improvement. Compare that to cplusplus.com. You are a perpetual newbie if you aren't on their staff. Even if you are a key member of WG21, you have to go through their email report mechanism if you see a bug somewhere in that site. Anathema!

A solution would be for us at this site to develop our own C++ reference. This would take quite a bit of work. We'd have to be careful not to be too pedantic / too technical; it is obvious that cplusplus.com employs at least a few technical editors who keep the pedants at bay. We'd have to keep the information well-organized; the FAQ here are not well organized. We'd also have to be very careful not to spout too much directly from the standard; that's illegal.

David Hammen
  • 30,597
  • 8
  • 54
  • 98
  • 8
    I used to frequent the old cppreference.com, but now they've reworked it into something wiki-ish (is it open to edit by everyone?) ... and I don't really like it any more. It's hard to see the important information, I find. It just lacks the immediate gratification I get from cplusplus.com. I think. – Kerrek SB Jun 29 '11 at 17:01
  • 16
    Whoa! I see the exact opposite. I stopped frequenting the old cppreference.com because I found it hard to traverse and poorly written. The new cppreference.com appears to be an ad-free, community-based site that does exactly what I suggested in my last paragraph. – David Hammen Jun 29 '11 at 17:19
  • 1
    Maybe it was just me, I shall give it another try. I think I wanted to look up some `` or `` stuff and just got "please write this page" so I gave up. Let me check again! Oh, C++0x support would of course be a huge bonus! – Kerrek SB Jun 29 '11 at 17:21
  • 12
    "People who live in glass houses shouldn't throw stones." SO doesn't claim to be (in part) a library reference for C++ as http://www.cplusplus.com/reference/ does. When people make claims here, they cite the standard to back them up, or if they don't then someone else comes along and fills in. If they're wrong, you can see their working. If cplusplus.com is wrong, you just wrote code that will fail on some C++ implementation other than the one that the author used to produce the "detailed description of its elements". The problem is that cplusplus.com is informal, but written to look formal. – Steve Jessop Jun 29 '11 at 18:50
  • 4
    SO is informal, and written to look informal. Now, if cplusplus.com is not intended to be accurate documentation/reference material and I've missed a disclaimer somewhere then fair enough, assume any stones to be thrown at the people who use it that way rather than the site itself. But the point is that just because cplusplus.com says something about a C++ function doesn't mean it's true, and it is worth knowing that if you plan to use it as a quick-reference. I use it to look up function signatures, but never to settle a fine point whether my code conforms or not. – Steve Jessop Jun 29 '11 at 18:53
16

http://www.cplusplus.com/reference/clibrary/cstring/strncpy/

Fails to mention that "If copying takes place between objects that overlap, the behavior is undefined." (4.11.2.4 in the C89 standard. I don't have a copy to hand of C90, which is what C++03 actually refers to, but they are supposed to differ only in stuff like page numbering.)

Steve Jessop
  • 257,525
  • 32
  • 431
  • 672
  • Ah, the old C library... nice. – Kerrek SB Jun 29 '11 at 12:41
  • 7
    They mention `destination and source shall not overlap`. – Sniper Apr 30 '17 at 09:50
  • 2
    @Sniper "shall not overlap" is **not** the same as "the behavior is undefined". Your comment actually illuminates one of the subtle, pervasive failings of cplusplus.com - it sounds right, but it's not correct. – Andrew Henle Jan 07 '20 at 14:03
  • @Sniper: I think probably it didn't say that when I made this answer in 2011. I would have taken "shall not overlap" as sufficient constraint on the inputs. – Steve Jessop May 25 '20 at 21:59
  • 1
    @AndrewHenle Actually, it's very common to use the term "shall not" to indicate undefined behavior. In fact, the C standard itself [does so](https://wiki.sei.cmu.edu/confluence/display/c/MSC15-C.+Do+not+depend+on+undefined+behavior#:~:text=If%20a%20%22shall%22%20or%20%22,any%20explicit%20definition%20of%20behavior.). Sorry I don't have the actual standard on me, just a secondary source. – Alexander Guyer Jan 23 '21 at 22:39
10

The documentation given by cplusplus.com is often incorrect or incomplete.

Once such example is ,the atoi documentation on cplusplus.com.

atoi
In Return section, there is no mentioning about 0 return value if no conversion can be performed while using the function.

cplusplus.com Return section states "...If the converted value would be out of the range of representable values by an int, it causes undefined behavior."

This is correct, as per the standard "If the numeric value of the string can't be represented in int, then the behaviour is undefined".

However the section is not full as it does not mention 0 as return value, which can be misleading. The phrase "...no conversion is performed and zero is returned." is met before in description paragraph, but it is essential to have it in Return section.

Many of the sample source codes given on cplusplus.com are incorrect.
Many of the newbies looking up to these references are led to making ballant errors.

To cite a example:

EDIT: The example I cited previously was incorrect.

Alexey Voytenko
  • 2,953
  • 2
  • 22
  • 35
Alok Save
  • 190,255
  • 43
  • 403
  • 518
  • 5
    Perhaps ballant -> blatant? However ballant is a French word for "dangling", which might be apropos for errors involving pointers. – hardmath Jun 29 '11 at 16:15
  • Reread that iterator example... there is no undefined behavior. – Dennis Zickefoose Jun 29 '11 at 16:27
  • 2
    You declared "Many of the sample source codes given on cplusplus.com are incorrect." and then removed the example saying "The example I cited previously was incorrect." - Why did you remove the example, then? :) – user2962533 Jun 15 '16 at 09:53
  • According to this site, the case that you describe results in an undefined return type not undefined behavior. http://en.cppreference.com/w/cpp/string/byte/atoi ; however, it looks like Cplusplus.com updated its documentation to match what you are saying. Evidently they do respond to community requests for corrections. Nevertheless, I'm not sure which website is most correct because the two in question state very different things. – shawn1874 Jun 09 '17 at 21:40
  • It has been 9 years since this answer was posted. Is it still generally believed that Cplusplus.com contains a significant amount of incorrect or incomplete information? – Tyler Shellberg Mar 11 '20 at 20:07
3

The documentation for type_info tries to explain typeid first, but fails:

typeid can be applied directly to types, in which case it returns its information; Or to objects, in which case it returns information on the type of the object.

When typeid is applied to a dereferenced pointer to an object of a polymorphic class type (a class declaring or inheriting a virtual function), it considers its dynamic type (i.e., the type of the most derived object).

Now the second paragraph already disagrees with the first. In typeid(*ptr), typeid is applied to an expression. This is rather essential, since the notion of static and dynamic types only makes sense in the context of expression, not objects. It also misses cases like typeid(foo()).

Furthermore, the second paragraph omits references. They too can have static types different from the dynamic type of the object they reference.

MSalters
  • 159,923
  • 8
  • 140
  • 320
  • Very nice - RTTI questions come up on SO with predictable regularity. Good to know what *not* to reference. – Kerrek SB Jun 29 '11 at 20:05
3

The documentation of std::pair<T1,T2>::operator== says that both elements are tested for equality. The documentation of std::pair<T1,T2>::operator< says that the second elements are considered only if the first elements are equal.

The word "equal" appears in both cases. Yet, only in the first case does it really mean T::operator==. In the second case, equal means !(a.first<b.first || b.first<a.first)

MSalters
  • 159,923
  • 8
  • 140
  • 320