-2

At the beginning of the page: https://learn.microsoft.com/en-us/cpp/mfc/reference/cstringlist-class?view=msvc-170

one can see the following line:

CObject*& CObList::GetHead() const;

Can you explain me what it is?

  1. It looks like a function declaration.
    Yet in a class .h file, we wouldn't prefix the function name with the class name CObList::

  2. Also, is CObject*& a function return type?

I am familiar with parameters passed as references using a & like for example:

void CMyClass::FindCountry(CString & szCountry)
{
    [...]
}
  1. What does the const keyword mean in that context?

Thanks.

Léa Massiot
  • 1,928
  • 6
  • 25
  • 43

1 Answers1

1
  1. It is a declaration of a CObList member function. It's not a proper C++ declaration (since it's done outside the class without a definition), but a declaration nevertheless.
  2. Yes, the function returns a reference to a CObject pointer.
  3. const means that the function promises to not change the CObList object. It's const qualified.
Ted Lyngmo
  • 93,841
  • 5
  • 60
  • 108
  • Thank you. Can you be so very kind to explain to me what it is useful for for a function to return a reference to a CObject pointer? Maybe you can give me an example? – Léa Massiot Mar 20 '23 at 15:51
  • Can you tell me what the < and > characters means in "POSITION AddHead( CObject* );" in the same documentation? Thanks. – Léa Massiot Mar 20 '23 at 16:01
  • 1
    @LéaMassiot You're welcome. Returning a pointer by reference makes it possible to bind to the original pointer. Calling `auto& obj = x.GetHead();` and then changing what `obj` points at will change the pointer returned by `GetHead()`. [Example](https://godbolt.org/z/j6MvsMn9G) – Ted Lyngmo Mar 20 '23 at 16:02
  • 1
    `` is just a documentation detail and is also not proper C++. They could have made it `newElement` instead to not confuse readers. – Ted Lyngmo Mar 20 '23 at 16:03
  • Thank you and especially for the example. In the `CObList::GetHead()` documentation, I can read: "If the list is accessed directly or through a pointer to a CObList, then GetHead returns a reference to a CObject pointer. This allows the function to be used on either side of an assignment statement and thus allows the list entries to be modified." Does it mean `GetHead()` can change the head of the list after all? If I relate to your example, a similar code would change the head, the first pointer in the list, wouldn't it? – Léa Massiot Mar 20 '23 at 16:23
  • @LéaMassiot Yes, that's correct. I don't know how `CObList` is implemented but if it's like a view over some externally allocated resource the `const` qualification will still honor the promise (since the actual `CObject*` it returns a reference to is owned "elsewhere") - or if it owns the resource, but the resource it is `mutable`, the `const` qualification would still not pose a problem. – Ted Lyngmo Mar 20 '23 at 16:37
  • Thank you. It is not easy to understand all the implications of such a declaration. In your example, ptr is not a member of the struct, it is "elsewhere". – Léa Massiot Mar 20 '23 at 18:47
  • @LéaMassiot Yes. In a real implementation I would assume some dynamic memory allocation and management instead of a single raw pointer though :-) – Ted Lyngmo Mar 20 '23 at 19:19