Sealed class: RT.KitchenSink.Collections.RVariant

Assembly: RT.Util.Legacy, Version=1.0.0.9999, Culture=neutral, PublicKeyToken=null
Namespace: RT.KitchenSink.Collections
Show inherited types...
Inherits from:
- object
Show implemented interfaces...
Implements:
- System.ICloneable (directly)
- System.Collections.Generic.ICollection<RT.KitchenSink.Collections.RVariant> (directly)
- System.Collections.IEnumerable (directly)
- System.Collections.Generic.IEnumerable<RT.KitchenSink.Collections.RVariant> (directly)
- System.IEquatable<RT.KitchenSink.Collections.RVariant> (directly)

Summary

Enables easy manipulation of simple hierarchical sets of values. Targets specifically the use of XML for storing application settings.

Examples:

RVariant v;
v = 3;                   // now stores the integer "3"
v = "hi there";          // now stores the string
v = DateTime.Now();      // stores current time

string s = v;            // s holds datetime in ISO, e.g. "2008-03-13 19:20:14.1230000Z"

v = new RVariant();      // v can become anything at the moment, known as Stub
v["form1"]["top"] = 20;  // v becomes a Dict, holding another dict, holding 20.
v["columns"][4] = "hi";  // v["columns"] holds a list: 0..3 are all Stubs, while
                         // item 4 holds "hi" and has path "columns[4]"

v["form2"] = v["form1"]; // deep copying

int i = v["form3"]["top"].OrDefaultTo(47);
                         // since form3/top does not exist, returns 47.
                         // but i = v["form3"]["top"]; throws an RVariantConvertException.

RVariant.ToXml(v, "settings").Save("settings.xml");
                         // save to an XML file

Properties that aid debugging:

v.FullPath  - the path to the given node in its hierarchy, e.g. "form2/top".
v.Kind      - one of the possible variant kinds: Stub, List, Dict, Value.
v.Value     - for Value variants, returns the value stored.

Constructors

RVariant()	Creates a Stub RVariant which has not yet assumed any specific behaviour. Such a node can be turned into a Value, a List or a Dict by performing an operation on it. E.g. indexing [] with an integer will turn it into a List.
RVariant(XmlDocument document)	Creates a RVariant from the specified XmlDocument. Does not tolerate errors - will throw an exception if the XML is not a valid representation of a RVariant.
RVariant(XmlDocument document, out string rootNodeName)	Creates a RVariant from the specified XmlDocument. Does not tolerate errors - will throw an exception if the XML is not a valid representation of a RVariant. The name of the root element will be stored in the "rootNodeName" parameter.
RVariant(XmlElement element)	Recreates a RVariant from the specified XmlElement. Can be used to store several RVariants in a single XmlDocument.

Instance methods

void	Add(RVariant item) Implements: ICollection<RVariant>.Add(RVariant)	Adds an RVariant to this variant, assuming/making it a List.
void	Clear() Implements: ICollection<RVariant>.Clear()	Makes this RVariant a stub, with no values associated. This is the only legal way to revert the RVariant.Kind from non-Stub to Stub.
object	Clone() Implements: ICloneable.Clone()	Creates a deep copy of this RVariant.
bool	Contains(RVariant item) Implements: ICollection<RVariant>.Contains(RVariant)	Not currently implemented.
void	CopyTo(RVariant[] array, int arrayIndex) Implements: ICollection<RVariant>.CopyTo(RVariant[], int)	Not currently implemented.
bool	Equals(object other) Overrides: object.Equals(object)	Compares this RVariant to another object. If the other object is a RVariant then performs a deep comparison of the two. Otherwise compares the Value stored in this RVariant with the specified object.
bool	Equals(RVariant other) Implements: IEquatable<RVariant>.Equals(RVariant)	Performs a deep comparison of this RVariant to another. The result is true only if the structure and every stored value is identical. Note that Paths are not taken into account so it is possible to compare two sub-values of different trees.
IEnumerator<RVariant>	GetEnumerator() Implements: IEnumerable<RVariant>.GetEnumerator()	Iterates over the items in this variant, assuming/making it a List.
int	GetHashCode() Overrides: object.GetHashCode()	Returns a hash code for this RVariant. Creates a deep recursive hash for Lists but not for Dicts. May be fairly slow - it's probably a bad idea to use RVariant as a dictionary key...
string	LoadFromXmlFile(string fileName)	Loads an XML file into this RVariant, deleting all existing values and adding new ones as appropriate.
bool	OrDefaultTo(bool defaultValue)	Treating this node as a Value, returns the value converted to a bool or the default value specified by defaultValue if the conversion is not possible. Also returns the default value if this node is not of a Value type.
byte	OrDefaultTo(byte defaultValue)	Treating this node as a Value, returns the value converted to a byte or the default value specified by defaultValue if the conversion is not possible. Also returns the default value if this node is not of a Value type.
sbyte	OrDefaultTo(sbyte defaultValue)	Treating this node as a Value, returns the value converted to an sbyte or the default value specified by defaultValue if the conversion is not possible. Also returns the default value if this node is not of a Value type.
short	OrDefaultTo(short defaultValue)	Treating this node as a Value, returns the value converted to a short or the default value specified by defaultValue if the conversion is not possible. Also returns the default value if this node is not of a Value type.
ushort	OrDefaultTo(ushort defaultValue)	Treating this node as a Value, returns the value converted to a ushort or the default value specified by defaultValue if the conversion is not possible. Also returns the default value if this node is not of a Value type.
int	OrDefaultTo(int defaultValue)	Treating this node as a Value, returns the value converted to an int or the default value specified by defaultValue if the conversion is not possible. Also returns the default value if this node is not of a Value type.
uint	OrDefaultTo(uint defaultValue)	Treating this node as a Value, returns the value converted to a uint or the default value specified by defaultValue if the conversion is not possible. Also returns the default value if this node is not of a Value type.
long	OrDefaultTo(long defaultValue)	Treating this node as a Value, returns the value converted to a long or the default value specified by defaultValue if the conversion is not possible. Also returns the default value if this node is not of a Value type.
ulong	OrDefaultTo(ulong defaultValue)	Treating this node as a Value, returns the value converted to a ulong or the default value specified by defaultValue if the conversion is not possible. Also returns the default value if this node is not of a Value type.
float	OrDefaultTo(float defaultValue)	Treating this node as a Value, returns the value converted to a float or the default value specified by defaultValue if the conversion is not possible. Also returns the default value if this node is not of a Value type.
double	OrDefaultTo(double defaultValue)	Treating this node as a Value, returns the value converted to a double or the default value specified by defaultValue if the conversion is not possible. Also returns the default value if this node is not of a Value type.
decimal	OrDefaultTo(decimal defaultValue)	Treating this node as a Value, returns the value converted to a decimal or the default value specified by defaultValue if the conversion is not possible. Also returns the default value if this node is not of a Value type.
DateTime	OrDefaultTo(DateTime defaultValue)	Treating this node as a Value, returns the value converted to a DateTime or the default value specified by defaultValue if the conversion is not possible. Also returns the default value if this node is not of a Value type.
char	OrDefaultTo(char defaultValue)	Treating this node as a Value, returns the value converted to a char or the default value specified by defaultValue if the conversion is not possible. Also returns the default value if this node is not of a Value type.
string	OrDefaultTo(string defaultValue)	Treating this node as a Value, returns the value converted to a string or the default value specified by defaultValue if the conversion is not possible. Also returns the default value if this node is not of a Value type.
bool	Remove(RVariant item) Implements: ICollection<RVariant>.Remove(RVariant)	Not currently implemented.
void	SaveToXmlFile(string fileName, string rootElementName)	Saves this RVariant to an XML file.
string	ToString() Overrides: object.ToString()	Returns a string representation of this RVariant. If this RVariant is of the Value Kind, returns the result of ExactConvert.ToString(object). Otherwise returns a string showing the Path and the Kind of this value.
XmlDocument	ToXml(string rootElementName)	Converts the specified RVariant to an XmlDocument. The name of the root element in the XmlDocument must be specified.
void	ToXml(XmlElement rootElement)	Converts the specified RVariant to XML, storing it in the specified XmlElement. The name of the destination XmlElement will not be altered.

Operators

bool	operator==(RVariant a, object b)	Compares RVariant to another object. If the RVariant and the object are not null, uses RVariant.Equals(object) to do the comparison.
bool	implicit operator bool(RVariant value)	Provides an implicit conversion of the RVariant to a bool. Throws an appropriate exception if the conversion is not possible.
byte	implicit operator byte(RVariant value)	Provides an implicit conversion of the RVariant to a byte. Throws an appropriate exception if the conversion is not possible.
sbyte	implicit operator sbyte(RVariant value)	Provides an implicit conversion of the RVariant to an sbyte. Throws an appropriate exception if the conversion is not possible.
short	implicit operator short(RVariant value)	Provides an implicit conversion of the RVariant to a short. Throws an appropriate exception if the conversion is not possible.
ushort	implicit operator ushort(RVariant value)	Provides an implicit conversion of the RVariant to a ushort. Throws an appropriate exception if the conversion is not possible.
int	implicit operator int(RVariant value)	Provides an implicit conversion of the RVariant to an int. Throws an appropriate exception if the conversion is not possible.
uint	implicit operator uint(RVariant value)	Provides an implicit conversion of the RVariant to a uint. Throws an appropriate exception if the conversion is not possible.
long	implicit operator long(RVariant value)	Provides an implicit conversion of the RVariant to a long. Throws an appropriate exception if the conversion is not possible.
ulong	implicit operator ulong(RVariant value)	Provides an implicit conversion of the RVariant to a ulong. Throws an appropriate exception if the conversion is not possible.
float	implicit operator float(RVariant value)	Provides an implicit conversion of the RVariant to a float. Throws an appropriate exception if the conversion is not possible.
double	implicit operator double(RVariant value)	Provides an implicit conversion of the RVariant to a double. Throws an appropriate exception if the conversion is not possible.
decimal	implicit operator decimal(RVariant value)	Provides an implicit conversion of the RVariant to a decimal. Throws an appropriate exception if the conversion is not possible.
DateTime	implicit operator DateTime(RVariant value)	Provides an implicit conversion of the RVariant to a DateTime. Throws an appropriate exception if the conversion is not possible.
char	implicit operator char(RVariant value)	Provides an implicit conversion of the RVariant to a char. Throws an appropriate exception if the conversion is not possible.
string	implicit operator string(RVariant value)	Provides an implicit conversion of the RVariant to a string. Throws an appropriate exception if the conversion is not possible.
RVariant	implicit operator RVariant(bool value)	Provides an implicit conversion of a bool to RVariant.
RVariant	implicit operator RVariant(byte value)	Provides an implicit conversion of a byte to RVariant.
RVariant	implicit operator RVariant(sbyte value)	Provides an implicit conversion of a sbyte to RVariant.
RVariant	implicit operator RVariant(short value)	Provides an implicit conversion of a short to RVariant.
RVariant	implicit operator RVariant(ushort value)	Provides an implicit conversion of a ushort to RVariant.
RVariant	implicit operator RVariant(int value)	Provides an implicit conversion of an int to RVariant.
RVariant	implicit operator RVariant(uint value)	Provides an implicit conversion of a uint to RVariant.
RVariant	implicit operator RVariant(long value)	Provides an implicit conversion of a long to RVariant.
RVariant	implicit operator RVariant(ulong value)	Provides an implicit conversion of a ulong to RVariant.
RVariant	implicit operator RVariant(float value)	Provides an implicit conversion of a float to RVariant.
RVariant	implicit operator RVariant(double value)	Provides an implicit conversion of a double to RVariant.
RVariant	implicit operator RVariant(decimal value)	Provides an implicit conversion of a decimal to RVariant.
RVariant	implicit operator RVariant(DateTime value)	Provides an implicit conversion of a DateTime to RVariant.
RVariant	implicit operator RVariant(char value)	Provides an implicit conversion of a char to RVariant.
RVariant	implicit operator RVariant(string value)	Provides an implicit conversion of a string to RVariant.
bool	operator!=(RVariant a, object b)	The opposite of RVariant.operator==(RVariant, object).

Instance properties

int	Count Implements: ICollection<RVariant>.Count	Gets the number of items stored in this variant. Returns 0 for Stubs and 1 for Values.
bool	Exists	Returns true if and only if this value is not a stub. This enables code like "settings["stuff"]["value"].Exists", which will return true only if the variant /stuff/value is defined.
string	FullPath	Gets the path of this variant. The path is null unless this variant is a Dict, a List or is contained in a Dict or a List. NOTE: This property is for debugging purposes only, since it is lossy and cannot reliably be split back into parts (since arbitrary Dict keys are allowed and are not escaped before use in this property)
string	FullPathNoNull	Same as the RVariant.FullPath property except that it never returns a null. If the path is null returns the string "<null-path>" instead. Note that, just like the FullPath property, this is only meant for debugging.
bool	IsReadOnly Implements: ICollection<RVariant>.IsReadOnly	Always returns false since RVariants are never read-only.
RVariant	this[string name]	Accesses a sub-element of this node, treating this node as a dictionary. Note that this will throw an exception if attempted on a node which is already a List or a Value.
RVariant	this[int index]	Accesses a sub-element of this node, treating this node as a list. Note that this will throw an exception if attempted on a node which is already a Dict or a Value.
RVariantKind	Kind	Defines which kind of node this RVariant represents: a List, a Dict or a Value. Can also be Stub if the node kind has not been determined yet.
object	Value	Gets the Value stored in this RVariant as an object. The object will be either a string or a boxed integer type. If the value has never been assigned an empty string will be returned. Will throw an exception if executed on a non-Value kind RVariant.