Move PPB_VarArray and PPB_VarDictionary out of dev.

ppapi/api/ppb_var_dictionary.idl

 /* Copyright (c) 2013 The Chromium Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 /**
- * This file defines the <code>PPB_VarDictionary_Dev</code> struct providing
+ * This file defines the <code>PPB_VarDictionary</code> struct providing
  * a way to interact with dictionary vars.
  */
 
 label Chrome {
-  M27 = 0.1
+  M29 = 1.0
 };
 
 /**
  * A dictionary var contains key-value pairs with unique keys. The keys are
  * strings while the values can be arbitrary vars. Key comparison is always
  * done by value instead of by reference.

[raymes, 2013/06/09 06:23:32]

noelallen: Not convinced this has to be a string.  For example it would be nice
if we could create a dictionary from an array, then add string keys later.
Doesn't have to be in rev 1.0 however.
In any case, I expect that developers will want PP_Var(s) that are ints, to
correctly index.   Otherwise, should we take a const char * the way that array
takes a uint32_t instead of a var?
NOTE: If the Pepper developer can't control how items are passed via JavaScript,
this could be problematic.  For example:

I believe this is consistent with JavaScript objects where property names can
only be strings. I believe the reason to have a PP_Var as the key type is
because GetKeys() returns a list of PP_Var. So this makes the [in] type for the
key, the same as the [out] type which just gives consistency to the interface.
yzshen@ might be able to comment more.

[dmichael (off chromium), 2013/06/11 17:19:47]

I had a similar discussion with Yuzhu a while back. It turns out:
"An object property name can be any valid JavaScript string, or anything that
can be converted to a string, including the empty string."
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Ob...
Also:
"Array elements are just object properties"
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Obje...
var a = ["Hello"];
console.log(a["0"]);
v8 certainly optimizes under the hood, but array elements really aren't
different from other properties in behavior (which surprised me, too).
Yeah, we talked about making it so that you can create a VarArray and also use
the VarDictionary interface on it. But the backend implementation would be a
little tricky (e.g., if you use VarDictionary to set a property with "0"
identifier, we have to check the array part to make sure it doesn't already have
that key. And vice versa when you add to the Array part. I don't think it would
give acceptable performance characteristics to just use a hash map to represent
Array.

So we might do something like that later, but yeah, not 1.0.
Using PP_Var allows us to take advantage of all the existing UTF8 checks we have
in place.

  */
-[macro="PPB_VAR_DICTIONARY_DEV_INTERFACE"]
-interface PPB_VarDictionary_Dev {
+[macro="PPB_VAR_DICTIONARY_INTERFACE"]
+interface PPB_VarDictionary {
   /**
    * Creates a dictionary var, i.e., a <code>PP_Var</code> with type set to
    * <code>PP_VARTYPE_DICTIONARY</code>.
    *
    * @return An empty dictionary var, whose reference count is set to 1 on
    * behalf of the caller.
    */
   PP_Var Create();
 
   /**
    * Gets the value associated with the specified key.
    *
    * @param[in] dict A dictionary var.
    * @param[in] key A string var.
    *
    * @return The value that is associated with <code>key</code>. The reference
-   * count is incremented on behalf of the caller. If <code>key</code> is not a
-   * string var, or it doesn't exist in <code>dict</code>, an undefined var is
-   * returned.
+   * count of the element returned is incremented on behalf of the caller. If
+   * <code>key</code> is not a string var, or it doesn't exist in
+   * <code>dict</code>, an undefined var is returned.
    */
   PP_Var Get([in] PP_Var dict, [in] PP_Var key);

[raymes, 2013/06/09 06:23:32]

Should this be:
  PP_Error Get([in] PP_Var dict, [in] PP_Var key, [out] PP_Var value)?
So that we can return PP_NO_KEY, PP_INVALID_KEY?
Otherwise we can not differentiate between a value that is currently set at
Undefined without also calling HasKey.
Is calling Set with a PP_Var undefined legal?   Is it possible to get an
undefined via a post message?
Maybe HasKey could return PP_OK, PP_NO_KEY, PP_INVALID_KEY...  instead?

I think returning undefined is reasonable because it matches the behavior of a
JavaScript object when the key doesn't exist. It is possible to receive an
undefined via PostMessage but undefined just signifies that no value has been
defined.

 
   /**
-   * Sets the value associated with the specified key. The dictionary is
-   * responsible for holding references to its children to keep them alive.
+   * Sets the value associated with the specified key.
    *
    * @param[in] dict A dictionary var.
    * @param[in] key A string var. If this key hasn't existed in
    * <code>dict</code>, it is added and associated with <code>value</code>;
    * otherwise, the previous value is replaced with <code>value</code>.
-   * @param[in] value The value to set.
+   * @param[in] value The value to set. The dictionary holds a reference to it
+   * on success.
    *
    * @return A <code>PP_Bool</code> indicating whether the operation succeeds.
    */
   PP_Bool Set([in] PP_Var dict, [in] PP_Var key, [in] PP_Var value);
 
   /**
-   * Deletes the specified key and its associated value, if the key exists.
+   * Deletes the specified key and its associated value, if the key exists. The
+   * reference to the element will be released.
    *
    * @param[in] dict A dictionary var.
    * @param[in] key A string var.
    */
   void Delete([in] PP_Var dict, [in] PP_Var key);
 
   /**
    * Checks whether a key exists.
    *
    * @param[in] dict A dictionary var.
@@ skipping 10 matching lines @@
    * be different).
    *
    * @param[in] dict A dictionary var.
    *
    * @return An array var which contains all the keys of <code>dict</code>. Its
    * reference count is incremented on behalf of the caller. The elements are
    * string vars. Returns a null var if failed.
    */
   PP_Var GetKeys([in] PP_Var dict);
 };