1.1 --- a/plugins/include/keyvalues.inc	Mon May 07 00:11:10 2007 +0000
     1.2 +++ b/plugins/include/keyvalues.inc	Mon May 07 02:58:58 2007 +0000
     1.3 @@ -176,21 +176,37 @@
     1.4  
     1.5  /**
     1.6   * Sets the current position in the KeyValues tree to the first sub key.
     1.7 + * This native adds to the internal traversal stack.
     1.8   *
     1.9   * @param kv			KeyValues Handle.
    1.10 + * @param keyOnly		If false, non-keys will be traversed (values).
    1.11   * @return				True on success, false if there was no first sub key.
    1.12   * @error				Invalid Handle.
    1.13   */
    1.14 -native bool:KvJumpFirstSubKey(Handle:kv);
    1.15 +native bool:KvGotoFirstSubKey(Handle:kv, bool:keyOnly=true);
    1.16  
    1.17  /**
    1.18   * Sets the current position in the KeyValues tree to the next sub key.
    1.19 + * This native does NOT add to the internal traversal stack, and thus
    1.20 + * KvGoBack() is not needed for each successive call to this function.
    1.21   *
    1.22   * @param kv			KeyValues Handle.
    1.23 + * @param keyOnly		If false, non-keys will be traversed (values).
    1.24   * @return				True on success, false if there was no next sub key.
    1.25   * @error				Invalid Handle.
    1.26   */
    1.27 -native bool:KvJumpNextSubKey(Handle:kv);
    1.28 +native bool:KvGotoNextKey(Handle:kv, bool:keyOnly=true);
    1.29 +
    1.30 +/**
    1.31 + * Saves the current position in the traversal stack onto the traversal
    1.32 + * stack.  This can be useful if you wish to use KvGotoNextKey() and 
    1.33 + * have the previous key saved for backwards traversal.
    1.34 + *
    1.35 + * @param kv			KeyValues Handle.
    1.36 + * @noreturn
    1.37 + * @error				Invalid Handle.
    1.38 + */
    1.39 +native KvSavePosition(Handle:kv);
    1.40  
    1.41  /**
    1.42   * Removes the given key from the current position.
    1.43 @@ -203,19 +219,27 @@
    1.44  native bool:KvDeleteKey(Handle:kv, const String:key[]);
    1.45  
    1.46  /**
    1.47 - * Removes the current sub-key and jumps back one position, using the previous
    1.48 - * position as the search point.  This will not work if used on the root node.
    1.49 + * Removes the current sub-key and attempts to set the position
    1.50 + * to the sub-key after the removed one.  If no such sub-key exists,
    1.51 + * the position will be the parent key in the traversal stack.
    1.52 + * Given the sub-key having position "N" in the traversal stack, the 
    1.53 + * removal will always take place from position "N-1."
    1.54   *
    1.55   * @param kv			KeyValues Handle.
    1.56 - * @return				True on success, false if there was no sub key.
    1.57 + * @return				1 if removal succeeded and there was another key.
    1.58 + *						0 if the current node was not contained in the
    1.59 + *						  previous node, or no previous node exists.
    1.60 + *						-1 if removal succeeded and there were no more keys,
    1.61 + *						  thus the state is as if KvGoBack() was called.
    1.62   * @error				Invalid Handle.
    1.63   */
    1.64 -native bool:KvDeleteThis(Handle:kv);
    1.65 +native KvDeleteThis(Handle:kv);
    1.66  
    1.67  /**
    1.68   * Jumps back to the previous position.  Returns false if there are no
    1.69   * previous positions (i.e., at the root node).  This should be called
    1.70   * once for each successful Jump call, in order to return to the top node.
    1.71 + * This function pops one node off the internal traversal stack.
    1.72   *
    1.73   * @param kv			KeyValues Handle.
    1.74   * @return				True on success, false if there is no higher node.