Why does the documentation on some languages say "equivalent to" rather than "is"?

For example, the Python Docs say



Equivalent to:

def chain(*iterables):
    # chain('ABC', 'DEF') --> A B C D E F
    for it in iterables:
        for element in it:
            yield element

Or this C++ reference on find_if:

The behavior of this function template is equivalent to:

template<class InputIterator, class UnaryPredicate>
  InputIterator find_if (InputIterator first, InputIterator last, UnaryPredicate pred)
  while (first!=last) {
    if (pred(*first)) return first;
  return last;

If that's not the actual code, can't they post it? And if it is the actual code, why do they have to say it's "Equivalent" rather than simply "is"?

  • 2
    Note that what you see for find_if is not "the" documentation for C++. If it was, then the cast to bool (which you see in the answer below) would be wrong. – user541686 Jan 15 '16 at 8:09
  • 3
    In the case of python if you look for the source code you'll find that chain is implemented directly in C, thus it is "equivalent" to that python code because it produces the same result, but it avoids a bit of overhead of interpreting that bytecode. – Bakuriu Jan 15 '16 at 20:12
  • @Mehrdad I'm aware it's not the official documentation, its just the resource I've found most helpful in finding out the particulars of C++ – Jon McClung Jan 15 '16 at 20:18
  • They'd be forced to use whatever approach was set in the standard, even if a significantly better one was available. – Kevin Sep 10 '17 at 5:34

Because the standard writers don't want to actually assert an implementation. They want to define what it does, but not necessarily how it does it. So, for example, if you look at the GNU C++ version of find_if, you will see that the implementation is slightly different from what you give, which is based on the C++ standard:

template<typename _InputIterator, typename _Predicate>
inline _InputIterator
__find_if(_InputIterator __first, _InputIterator __last,
    _Predicate __pred, input_iterator_tag)
    while (__first != __last && !bool(__pred(*__first)))
       return __first;

This is functionally equivalent to what the standard has, but not exactly the same. This gives compiler writers flexibility. There may be a better way to do it for a particular platform. The implementor may wish to use a different coding style.

This is particularly true for scripting languages like python in that the implementor may decided to implement in a completely different language for performance reasons. Someone implementing python may, for instance, write itertools.chain(*iterables) in C++. This is perfectly fine if the standard says "equivalent to" as long as the code does the same as the provided python. If the standard said "is" instead, then implementors would be required to either implement in that language, or not meet the standard.

In summary:

  1. Because they don't want to prevent an implementation from writing better code than the standard provided
  2. Because they don't want to prevent an implementation from using an entirely different language, to improve performance
| improve this answer | |
  • Thank you for the enlightening answer! I suspected the answer was something along those lines. – Jon McClung Jan 15 '16 at 5:09
  • @lerenard, you may find it further enlightening to read the full implementation of find_if from Steven's link. (What's he's got there is really just an excerpt.) – Winston Ewert Jan 15 '16 at 5:12
  • @WinstonEwert, Unfortunately I'm not quite at the level of fully understanding code like that, but the liberal use of underscores is certainly a point of interest! – Jon McClung Jan 15 '16 at 5:18
  • 9
    @lerenard: Those additional leading underscores are there so that the standard library internals don't interfere with the code you might write (names with double leading underscores are reserved for use by the compiler/standard library writers). – Bart van Ingen Schenau Jan 15 '16 at 7:43
  • 5
    Well, in C and C++, there's always the as-if-rule, so even if the standard said is instead of equivalent to, the actual implementation might differ. – Deduplicator Jan 15 '16 at 13:42

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.