fix #12519: introduce OrderedTable.take, CountTable.del, CountTable.take

[narimiran]

Rationale: these procs exist for Table, they should also exist for OrderedTable and CountTable.

Fixes #12519.

[Araq]

Needs the upcoming .since annotation. So it's delayed for now.

[narimiran]

Needs the upcoming .since annotation. So it's delayed for now.

Done.

[Araq]

No changelog entry?

[narimiran]

No changelog entry?

Done :)

[c-blake]

I realize this naming is patterned after the 2 year old Table.take, but Nim's seq and HashSet also already have similar remove-and-return operations called pop. I didn't say anything about Table.take back then, but thought it worth bringing up before we solidify this naming in the Table family.

Also, this operation is not really covered in doc/apis.rst, but should be. I also think the naming analogy with seq makes it more intuitive that pop might need to be called multiple times to undo a series of same-key adds. Tagging @cdunn2001 since he was recently updating take documentation along those lines.

(Less relevant than Nim-internal consistency, but Python also calls it pop, and take seems more a verb from functional programming language communities which Nim does seem to imitate more generally.)

My vote would be to name this pop and have Table.take either become deprecated or just be along-for-the-ride-forever for the sake of 1.0 series backward compatibility.

[c-blake]

(And of course there are also pop variations in heapqueue.nim and deques.nim. It sure feels like pop is the super majority vote internally while take was a singleton until this PR.)