Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

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

For example, the Python Docs say

itertools.chain(*iterables)

...

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;
    ++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"?

share|improve this question
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. – Mehrdad Jan 15 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 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 at 20:18
up vote 60 down vote accepted

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)))
     ++__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
share|improve this answer
    
Thank you for the enlightening answer! I suspected the answer was something along those lines. – Jon McClung Jan 15 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 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 at 5:18
8  
@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 at 7:43
1  
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 at 13:42

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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