Re: Inconsistency between results of pretty-printing children

[Tom Tromey <tromey@redhat.com>]

>>>>> "Oliver" == Oliver Buchtala <oliver.buchtala@googlemail.com> writes:

Oliver> here the doc:
Oliver> http://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing-API.html
Oliver> under display_hint "map"

Ok, I see.

In the 'map' case, each item returned by the 'children' iterator must
still be a 2-tuple of the form (NAME VALUE).

What 'map' means is that the first item fetched from the iterator is
considered to be a key in the map, and the second item fetched from the
iterator is considered to be the corresponding value.  Then the 3rd item
is a key again, the 4th is a value again, and so on.

In the CLI the NAME parts are omitted when printing, in this case, just
because it makes the output prettier.

In MI, nothing changes -- the hint is emitted and the MI client is
expected to take whatever action it thinks appropriate.


Here's an abbreviated example from the libstdc++ test suite:

  std::map<std::string, int> mp;
  mp["zardoz"] = 23;
// { dg-final { note-test mp {std::map with 1 elements = {["zardoz"] = 23}} } }

That last line means that 'print mp' here should show:

    std::map with 1 elements = {["zardoz"] = 23}

If you dig into the libstdc++ StdMapPrinter code you see:

        def next(self):
            if self.count % 2 == 0:
                n = self.rbiter.next()
                n = n.cast(self.type).dereference()['_M_value_field']
                self.pair = n
                item = n['first']
            else:
                item = self.pair['second']
            result = ('[%d]' % self.count, item)
            self.count = self.count + 1
            return result

So in the example above it returns a list like

    [ ('[0]', '"zardoz"'), ('[1]', 23) ]



My question for you is: how can we improve the documentation to make
this more clear?

Right now they read:

@item map
Indicate that the object being printed is ``map-like'', and that the
children of this value can be assumed to alternate between keys and
values.


Tom