Move PPB_VarArray and PPB_VarDictionary out of dev.

ppapi/api/ppb_var_dictionary.idl

Index: ppapi/api/ppb_var_dictionary.idl
diff --git a/ppapi/api/dev/ppb_var_dictionary_dev.idl b/ppapi/api/ppb_var_dictionary.idl
similarity index 81%
rename from ppapi/api/dev/ppb_var_dictionary_dev.idl
rename to ppapi/api/ppb_var_dictionary.idl
index f3e7407438ac430b94d51727ab6660d8890d108f..1464bc615a764066885b16eec1ee2d432bab02df 100644
--- a/ppapi/api/dev/ppb_var_dictionary_dev.idl
+++ b/ppapi/api/ppb_var_dictionary.idl
@@ -4,12 +4,12 @@
  */
 
 /**
- * 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
 };
 
 /**
@@ -17,8 +17,8 @@ label Chrome {
  * 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>.
@@ -35,28 +35,29 @@ interface PPB_VarDictionary_Dev {
    * @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.