Note that each in scalar context returns the next key.

One of the things I rarely use.

each iterates over the keys of a hash, returning different values when called repeatedly.

>perl -E '%h=map{ $_ => 1 } qw( a b c d e f ); while ($k=each %h) { sa
+y $k }'
a
c
d
b
f
e

>
[download]

But the MUMPS $ORDER() function is different. Keys in MUMPS are always sorted, unlike Perl's hash keys. And keys must not be empty. $ORDER() returns the next key for the key you pass into. It does not iterate. Passing -1 as a second argument to $ORDER() returns the previous key instead of the next one. If there is no previous / next key, an empty string is returned.

  KILL ^H
  SET ^H("D")=1
  SET ^H("E")=1,^H("F")=1
  S ^H("A")=1,^H("B")=1,^H("C")=1
  ; ^-- ^H now contains the keys "A", "B", "C", "D", "E", "F"
  ;
  WRITE $ORDER(^H("")),!
  ; ^-- writes "A", the first key (in order) of ^H
  ;
  W $O(^H("C")),!
  ; ^-- writes "D", the next key after "C" in ^H
  ;
  W $O(^H("F")),!
  ; ^-- writes "", because "F" is the last key in ^H
  ;
  W $O(^H("D"),-1),!
  ; ^-- writes "C", the key before "D" in ^H
  ;
  W $O(^H("A"),-1),!
  ; ^-- writes "", because "A" is the first key in ^H
  ;
  SET K="" FOR  SET K=$ORDER(^H(K)) QUIT:K=""  DO
  .WRITE K
  WRITE !
  ; ^-- writes "ABCDEF", all keys of ^H in order
  ;
  S K="" F  S K=$O(^H(K,-1)) Q:K=""  D
  .W K
  W !
  ; ^-- writes "FEDCBA", all keys of ^H in reverse order (-1 passed as
+ second argument to $ORDER)
  ;
  S K="B" F  S K=$O(^H(K)) Q:K=""  Q:K="E"  D
  .W K
  W !
  ; ^-- writes "CD", all keys of ^H following "B" and stopping at the 
+end of keys or at "E", in order
  ;
  S K="B" F  S K=$O(^H(K)) Q:K=""  Q:K]]"E"  D
  .W K
  W !
  ; ^-- writes "CDE", all keys of ^H following "B" and stopping at the
+ end of keys or at the first key sorting after "E", in order
[download]

Actually, $ORDER() is a "new" (*cough*) function, it can handle negative and non-numeric keys. The original function used to iterate over keys was $NEXT(), and it was intended to be used only with positive integers, i.e. plain arrays or sparse arrays. It returns -1 if no more keys can be found. Unfortunately, -1 is a legal key. So if $NEXT() returns -1, you can not know if you found the last key or you just happen to have -1 as a key. $ORDER() fixes that problem, and $NEXT() is provided for legacy code from the dark ages.

Alexander