// Copyright 2016 The Bazel Authors. All rights reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package com.google.devtools.build.lib.syntax; import com.google.common.annotations.VisibleForTesting; import com.google.devtools.build.lib.events.Location; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.skylarkinterface.SkylarkPrinter; import com.google.devtools.build.lib.syntax.SkylarkMutable.MutableMap; import java.util.Collections; import java.util.LinkedHashMap; import java.util.Map; import javax.annotation.Nullable; /** * A Skylark dictionary (dict). * *
Although this implements the {@link Map} interface, it is not mutable via that interface's
* methods. Instead, use the mutators that take in a {@link Mutability} object.
*/
@SkylarkModule(
name = "dict",
category = SkylarkModuleCategory.BUILTIN,
doc =
"A language built-in type representating a dictionary (associative mapping). "
+ "Dictionaries may be constructed with a special literal syntax:
"
+ "
d = {\"a\": 2, \"b\": 5}" + "See also the dict() constructor function. " + "When using the literal syntax, it is an error to have duplicated keys. " + "Use square brackets to access elements:
e = d[\"a\"] # e == 2" + "Like lists, they can also be constructed using a comprehension syntax:
d = {i: 2*i for i in range(20)}\n" + "e = d[8] # e == 16" + "Dictionaries are mutable. You can add new elements or mutate existing ones:" + "
d[\"key\"] = 5" + "
Iterating over a dict is equivalent to iterating over its keys. The "
+ "in
operator tests for membership in the keyset of the dict.
"
+ "
\"a\" in {\"a\" : 2, \"b\" : 5} " + "# evaluates as True" + "The iteration order for a dict is deterministic but not specified." ) public final class SkylarkDict
The returned map may or may not be a view that is affected by updates to the original dict.
*
* @param obj the object to cast. null and None are treated as an empty dict.
* @param keyType the expected type of all the dict's keys
* @param valueType the expected type of all the dict's values
* @param description a description of the argument being converted, or null, for debugging
*/
public static The returned map may or may not be a view that is affected by updates to the original dict.
*
* @param keyType the expected class of keys
* @param valueType the expected class of values
* @param description a description of the argument being converted, or null, for debugging
*/
@SuppressWarnings("unchecked")
public