The bundle is a main concept of the CotC SDK. It is basically the equivalent of a JSON object, behaving like a C# dictionary, but with inferred typing and more safety.
You need bundles in many calls, either to decode generic data received by the server (when such data can be enriched by hooks typically) or to pass generic user parameters, such as when creating a match.
Bundles are instantiated through their factory methods: Bundle.CreateObject or Bundle.CreateArray. The type of the resulting object can be inspected via the Type member. While objects and arrays are containers for further objects, a bundle is a simple node in the graph and may as such contain a value, such as a string.
Sub-objects are fetched using the index operator (brackets), either with a numeric argument for arrays or a string argument for dictionaries. Conversions are performed automatically based. Let's consider the following example:
The bundle object, considered as dictionary will have its key "hello" set with a new Bundle node of type string (implicitly created from the string). So later on, you might fetch this value as well:
string value = b["hello"];
What happens here is that the bundle under the key "hello" is fetched, and then implicitly converted to a string.
Bundle provides a safe way to browse a predefined graph, as when a key doesn't exist it returns the Bundle.Empty (no null value). This special bundle allows to fetch sub-objects but they will always translate to Bundle.Empty as well. If the values are to be converted to a primitive type, the result will be the default value for this type (null for a string, 0 for an int, etc.). As such, you may do this:
int value = bundle["nonexisting"]["key"];
Since the "nonexisting" key is not found on bundle, Bundle.Empty is returned. Further fetching "key" will return an empty bundle as well. Which will be converted implicitly to an integer as 0. Bundle.Empty is a constant value that always refers to an empty bundle, and attempting to modify it will result in an exception.
b["value"] = "something";
The bundle hierarchy doesn't accept null or Bundle.Empty values (it just rejects them). You should avoid manipulating null Bundles and use Bundle.Empty wherever possible, however you may assign a null bundle to a key, which will have no effect. This can be useful for optional arguments. For instance, the following snippet will not affect the bundle.
string value = null;
bundle["key"] = value;
Note that Bundle.Empty is not strictly identical to an empty bundle object. Bundle.Empty is never considered as a value and is discarded upon assignment. For instance:
b[
"key"] =
Bundle.CreateObject();
Log(a.ToJson());
Log(b.ToJson());
If you need a special value for keys that do not match the expected type or are not found in the hierarchy, you may as well use the .As* methods. For instance, the previous snippet could be written as follows to have a default value of one:
int value = bundle["nonexisting"]["key"].AsInt(1);
It is also possible to inspect the Type property of the Bundle in order to ensure that the value was provided as expected.
A bundle may be pre-filled at creation by passing arguments to Bundle.CreateObject and Bundle.CreateArray. For instance:
Bundle b =
Bundle.CreateObject(
"key1",
"value1",
"key2",
"value2");
Is equivalent to writing:
b["key1"] = "value1";
b["key2"] = "value2";
A bundle can quickly be transformed from/to JSON using ToJson and Bundle.FromJson methods. One can also check for the presence of keys and remove them with the .Has respectively .Remove methods.
Iterating a JSON object is made using the explicit .As* methods. For instance, here is how you iterate over an array bundle (no harm will happen if the key doesn't exist or is not an array, since an empty array is returned):
foreach (
Bundle value
in b) { ... }
For an object, use AsDictionary().
foreach (KeyValuePair<string, Bundle> pair
in b[
"key"].
AsDictionary()) { ... }
This loop is safe as well even if the bundle doesn't contain a "key" entry or the "key" entry is not an object.
Null bundles should be avoided! Use Bundle.Empty every time you need a "void", non mutable bundle value. Converting from a null bundle will result in an exception.
That's all what there is to know about bundles. In general they should make any code interacting with generic objects simple and safe.
|
| Bundle (bool value) |
| Creates a new Bundle of Boolean type from a bool value. More...
|
|
| Bundle (int value) |
| Creates a new Bundle of Integer type from an int value. More...
|
|
| Bundle (long value) |
| Creates a new Bundle of Integer type from a long value. More...
|
|
| Bundle (float value) |
| Creates a new Bundle of Double type from a float value. More...
|
|
| Bundle (double value) |
| Creates a new Bundle of Double type from a double value. More...
|
|
| Bundle (string value) |
| Creates a new Bundle of String type from a string value. More...
|
|
override int | GetHashCode () |
| Call the standard Object.GetHashCode() method to compute a hash code for this Bundle. More...
|
|
bool | Equals (Bundle b) |
| Compares the Bundle with another one to find out if they are equal. Compares instances references first, then tries to compare Bundles' values. Warning: The converted values are actually compared, then a "1" integer or string type Bundle would match a "true" bool type Bundle for example. More...
|
|
override bool | Equals (object obj) |
| Compares the Bundle with any object (expected to be another Bundle) to find out if they are equal. Compares instances references first, then tries to compare Bundles' values. Warning: The converted values are actually compared, then a "1" integer or string type Bundle would match a "true" bool type Bundle for example. More...
|
|
bool | Has (string key) |
| Tests if an object type (Dictionary) Bundle has a given key defined. More...
|
|
void | Remove (string key) |
| Removes an object type (Dictionary) Bundle's key value. More...
|
|
void | Add (Bundle value) |
| Adds a Bundle value to this array-type (List) Bundle. More...
|
|
Bundle | Clone () |
| Deep copies the bundle. More...
|
|
bool | GetBool (string key, bool defaultValue=false) |
| Gets an object type (Dictionary) Bundle's key bool value. More...
|
|
int | GetInt (string key, int defaultValue=0) |
| Gets an object type (Dictionary) Bundle's key int value. More...
|
|
long | GetLong (string key, long defaultValue=0L) |
| Gets an object type (Dictionary) Bundle's key long value. More...
|
|
float | GetFloat (string key, float defaultValue=0f) |
| Gets an object type (Dictionary) Bundle's key float value. More...
|
|
double | GetDouble (string key, double defaultValue=0d) |
| Gets an object type (Dictionary) Bundle's key double value. More...
|
|
string | GetString (string key, string defaultValue=null) |
| Gets an object type (Dictionary) Bundle's key string value. More...
|
|
bool | GetBool (int index, bool defaultValue=false) |
| Gets an array type (List) Bundle's index bool value. More...
|
|
int | GetInt (int index, int defaultValue=0) |
| Gets an array type (List) Bundle's index int value. More...
|
|
long | GetLong (int index, long defaultValue=0L) |
| Gets an array type (List) Bundle's index long value. More...
|
|
float | GetFloat (int index, float defaultValue=0f) |
| Gets an array type (List) Bundle's index float value. More...
|
|
double | GetDouble (int index, double defaultValue=0d) |
| Gets an array type (List) Bundle's index double value. More...
|
|
string | GetString (int index, string defaultValue=null) |
| Gets an array type (List) Bundle's index string value. More...
|
|
bool | AsBool (bool defaultValue=false) |
| Gets a Bundle's value as a bool converted value. More...
|
|
int | AsInt (int defaultValue=0) |
| Gets a Bundle's value as a int converted value. More...
|
|
long | AsLong (long defaultValue=0L) |
| Gets a Bundle's value as a long converted value. More...
|
|
float | AsFloat (float defaultValue=0f) |
| Gets a Bundle's value as a float converted value. More...
|
|
double | AsDouble (double defaultValue=0d) |
| Gets a Bundle's value as a double converted value. More...
|
|
string | AsString (string defaultValue=null) |
| Gets a Bundle's value as a string converted value. More...
|
|
Dictionary< string, Bundle > | AsDictionary () |
| Gets object type Bundle as a Dictionary. More...
|
|
List< Bundle > | AsArray () |
| Gets array type Bundle as a List. More...
|
|
string | ToJson () |
| Gets all bundle's data as a json-like string. More...
|
|
override string | ToString () |
| Gets all bundle's data as a human readable string. (actually calls ToJson()) More...
|
|
|
static Bundle | CreateObject () |
| Creates a bundle of type object. More...
|
|
static Bundle | CreateObject (string key, Bundle value) |
| Creates a bundle of type object with one key/value pair which will be put in the object initially. More...
|
|
static Bundle | CreateObject (string key1, Bundle value1, string key2, Bundle value2) |
| Creates a bundle of type object with two key/value pairs which will be put in the object initially. More...
|
|
static Bundle | CreateObject (string key1, Bundle value1, string key2, Bundle value2, string key3, Bundle value3) |
| Creates a bundle of type object with three key/value pairs which will be put in the object initially. More...
|
|
static Bundle | CreateObject (params KeyValuePair< string, Bundle >[] keyValuePairs) |
| Creates a bundle of type object with many key/value pairs which will be put in the object initially. More...
|
|
static Bundle | CreateArray (params Bundle[] values) |
| Creates a bundle of type array. More...
|
|
static implicit | operator Bundle (bool value) |
| Implicitly creates a new Bundle of Boolean type from a bool value. More...
|
|
static implicit | operator Bundle (int value) |
| Implicitly creates a new Bundle of Integer type from an int value. More...
|
|
static implicit | operator Bundle (long value) |
| Implicitly creates a new Bundle of Integer type from a long value. More...
|
|
static implicit | operator Bundle (float value) |
| Implicitly creates a new Bundle of Double type from a float value. More...
|
|
static implicit | operator Bundle (double value) |
| Implicitly creates a new Bundle of Double type from a double value. More...
|
|
static implicit | operator Bundle (string value) |
| Implicitly creates a new Bundle of String type from a string value. More...
|
|
static implicit | operator bool (Bundle b) |
| Implicitly gets a Bundle's value as a bool converted value. More...
|
|
static implicit | operator int (Bundle b) |
| Implicitly gets a Bundle's value as an int converted value. More...
|
|
static implicit | operator long (Bundle b) |
| Implicitly gets a Bundle's value as a long converted value. More...
|
|
static implicit | operator float (Bundle b) |
| Implicitly gets a Bundle's value as a float converted value. More...
|
|
static implicit | operator double (Bundle b) |
| Implicitly gets a Bundle's value as a double converted value. More...
|
|
static implicit | operator string (Bundle b) |
| Implicitly gets a Bundle's value as a string converted value. More...
|
|
static bool | operator== (Bundle b, object obj) |
| Compares the Bundle with any object (expected to be another Bundle) to find out if they are equal. Compares instances references first, then tries to compare Bundles' values. Warning: The converted values are actually compared, then a "1" integer or string type Bundle would match a "true" bool type Bundle for example. More...
|
|
static bool | operator != (Bundle b, object obj) |
| Compares the Bundle with any object (expected to be another Bundle) to find out if they are different. Compares instances references first, then tries to compare Bundles' values. Warning: The converted values are actually compared, then a "1" integer or string type Bundle would match a "true" bool type Bundle for example. More...
|
|
static Bundle | FromAnyJson (string json) |
| Builds a complete Bundle hierarchy representing data from a json-like string. Works even if the root json token is a simple value type like a string or a number. More...
|
|
static Bundle | FromJson (string json) |
| Builds a complete Bundle hierarchy representing data from a json-like string. Works only if the root json token is an object or an array, but not a simple value type like a string or a number (in this case use FromAnyJson() instead). More...
|
|