note

VeloxDB is still in beta and APIs are subject to change. We are in the process of completing the documentation, so some sections may be incomplete or empty at this time.

Class ReferenceArray<T>

Represents an array of references to database objects.

Inheritance
System.Object
ReferenceArray
ReferenceArray<T>
Implements
System.Collections.Generic.IList<T>
System.Collections.Generic.ICollection<T>
System.Collections.Generic.IEnumerable<T>
System.Collections.IEnumerable
Namespace: VeloxDB.ObjectInterface
Assembly: vlxdb.dll
Syntax
public sealed class ReferenceArray<T> : ReferenceArray, IList<T>, ICollection<T>, IEnumerable<T>, IEnumerable where T : DatabaseObject
Type Parameters
Name Description
T

The type of items in the array.

Remarks

VeloxDB allows you to specify an array like collection. ReferenceArray<T> can only hold references to DatabaseObject, if you need an array of references to simple types, use DatabaseArray<T>. ReferenceArray<T> property must be marked with DatabaseReferenceAttribute attribute because it represents a reference to another DatabaseObject.

ReferenceArray<T> is backed by an array. Array's size is initially set to capacity. As long as the capacity is larger than the length of the array Add is constant time operation (O(1)). When there is no more space in the backing array new array is allocated. The new array is twice the size of the previous one. Contents of the old array are copied to the new array. This gives ReferenceArray<T> amortized constant time adds, constant time direct access and linear remove.

Examples

The following example demonstrates how to declare a ReferenceArray<T> property.


[DatabaseClass]
[HashIndex("name", true, nameof(City.Name))]
public abstract class City : DatabaseObject
{
    [DatabaseProperty]
    public abstract string Name { get; set; }

    [DatabaseReference]
    public abstract ReferenceArray<WeatherStation> Stations {get; set;}
}

The following example demonstrates how to use a ReferenceArray<T>.

[DbAPIOperation]
public void CreateTestCity(ObjectModel om)
{
    City city = om.CreateObject<City>();

    city.Stations = new ReferenceArray<WeatherStation>();

    WeatherStation ws;
    for (int i = 0; i < 4; i++)
    {
        ws = om.CreateObject<WeatherStation>();
        city.Stations.Add(ws);
    }

    // Get a WeatherStation by index
    ws = city.Stations[2];

    // Remove using object
    city.Stations.Remove(ws);

    // Remove using index
    city.Stations.RemoveAt(0);

    // Clear
    city.Stations.Clear();
}

Constructors

ReferenceArray()

Creates a new empty instance of the ReferenceArray<T>.

Declaration
public ReferenceArray()

ReferenceArray(IEnumerable<T>)

Creates a new instance of the ReferenceArray<T> that contains elements copied from the supplied collection.

Declaration
public ReferenceArray(IEnumerable<T> collection)
Parameters
Type Name Description
System.Collections.Generic.IEnumerable<T> collection

The collection whose elements are to be copied.
Exceptions
Type Condition
System.ArgumentNullException

collection is null or an item in the collection is null.
System.ArgumentException

If any item in collection is a deleted item.

ReferenceArray(Int32)

Creates a new empty instance of the ReferenceArray<T>. With specified capacity.

Declaration
public ReferenceArray(int capacity = 4)
Parameters
Type Name Description
System.Int32 capacity

Initial capacity. The initial size of the backing array.

Properties

Count

Gets the number of items contained in the ReferenceArray<T>.

Declaration
public override int Count { get; }
Property Value
Type Description
System.Int32
Overrides
Exceptions
Type Condition
System.InvalidOperationException

If the parent object of the DatabaseArray<T> has been deleted or abandoned.
System.ObjectDisposedException

If the parent object of the DatabaseArray<T> has been disposed.

IsReadOnly

Gets if the ReferenceArray<T> is Readonly. Always returns false.

Declaration
public bool IsReadOnly { get; }
Property Value
Type Description
System.Boolean

Item[Int32]

Index accessor.

Declaration
public T this[int index] { get; set; }
Parameters
Type Name Description
System.Int32 index

Index of the item to get.
Property Value
Type Description
T

Requested item.
Exceptions
Type Condition
System.IndexOutOfRangeException

If index is less than 0 or greater than Count
System.InvalidOperationException

If the parent object of the DatabaseArray<T> has been deleted or abandoned.
System.ObjectDisposedException

If the parent object of the DatabaseArray<T> has been disposed.

Methods

Add(T)

Add an item to the end of the ReferenceArray<T>.

Declaration
public void Add(T item)
Parameters
Type Name Description
T item

The item to be added to the end of the ReferenceArray<T>.
Exceptions
Type Condition
System.ArgumentNullException

item is null
System.InvalidOperationException

If the added item would cause Count to exceed int.MaxValue
or
If the parent object of the ReferenceArray<T> has been deleted or abandoned.
System.ObjectDisposedException

If the parent object of the ReferenceArray<T> has been disposed.

AddRange(IEnumerable<T>)

Adds the elements of the specified collection to the end of the DatabaseArray<T>.

Declaration
public void AddRange(IEnumerable<T> collection)
Parameters
Type Name Description
System.Collections.Generic.IEnumerable<T> collection

Collection whose elements will be added.
Exceptions
Type Condition
System.ArgumentNullException

collection is null.

Clear()

Clears the ReferenceArray<T>.

Declaration
public void Clear()
Exceptions
Type Condition
System.InvalidOperationException

If the parent object of the ReferenceArray<T> has been deleted or abandoned.
System.ObjectDisposedException

If the parent object of the ReferenceArray<T> has been disposed.

Contains(T)

Determines if an item is in the ReferenceArray<T>.

Declaration
public bool Contains(T item)
Parameters
Type Name Description
T item

The item to locate in the ReferenceArray<T>.
Returns
Type Description
System.Boolean

true if item is present in the ReferenceArray<T>, false if not.
Exceptions
Type Condition
System.ArgumentNullException

item is null.
System.InvalidOperationException

If the parent object of the ReferenceArray<T> has been deleted or abandoned.
System.ObjectDisposedException

If the parent object of the ReferenceArray<T> has been disposed.

CopyTo(T[], Int32)

Copies all items from the ReferenceArray<T> to the given array, starting at the specified index of the target array.

Declaration
public void CopyTo(T[] array, int arrayIndex)
Parameters
Type Name Description
T[] array

Destination array.
System.Int32 arrayIndex

Zero based index in array at which copying begins.
Exceptions
Type Condition
System.ArgumentNullException

array is null.
System.ArgumentException

There is not enough space in array to accommodate all the items.
System.ArgumentOutOfRangeException

arrayIndex is less than 0.
System.InvalidOperationException

If the parent object of the ReferenceArray<T> has been deleted or abandoned.
System.ObjectDisposedException

If the parent object of the ReferenceArray<T> has been disposed.

GetEnumerator()

Returns an enumerator that iterates through ReferenceArray<T>.

Declaration
public IEnumerator<T> GetEnumerator()
Returns
Type Description
System.Collections.Generic.IEnumerator<T>

An enumerator.
Remarks

If ReferenceArray<T> changes, enumerator is invalidated. Any attempts to use it after that will throw an System.InvalidOperationException.

Exceptions
Type Condition
System.InvalidOperationException

If the parent object of the ReferenceArray<T> has been deleted or abandoned.
System.ObjectDisposedException

If the parent object of the ReferenceArray<T> has been disposed.

IndexOf(T)

Finds an item in the ReferenceArray<T> and returns its position.

Declaration
public int IndexOf(T item)
Parameters
Type Name Description
T item

Item to find in ReferenceArray<T>.
Returns
Type Description
System.Int32

If the element is found, it return the zero based index in ReferenceArray<T>, otherwise it returns -1.
Exceptions
Type Condition
System.ArgumentNullException

item is null.
System.InvalidOperationException

If the parent object of the ReferenceArray<T> has been deleted or abandoned.
System.ObjectDisposedException

If the parent object of the ReferenceArray<T> has been disposed.

Insert(Int32, T)

Inserts an item into ReferenceArray<T> at the specified position.

Declaration
public void Insert(int index, T item)
Parameters
Type Name Description
System.Int32 index

Zero based position at which to insert item.
T item

The item to insert.
Exceptions
Type Condition
System.ArgumentNullException

item is null.
System.ArgumentOutOfRangeException

If index is less than 0 or greater than Count
System.InvalidOperationException

If the parent object of the ReferenceArray<T> has been deleted or abandoned.
System.ObjectDisposedException

If the parent object of the ReferenceArray<T> has been disposed.

Remove(T)

Remove the first occurrence of the item from the ReferenceArray<T>.

Declaration
public bool Remove(T item)
Parameters
Type Name Description
T item

Item to be removed.
Returns
Type Description
System.Boolean

true if item was removed, otherwise false.
Exceptions
Type Condition
System.ArgumentNullException

item is null.
System.InvalidOperationException

If the parent object of the ReferenceArray<T> has been deleted or abandoned.
System.ObjectDisposedException

If the parent object of the ReferenceArray<T> has been disposed.

RemoveAt(Int32)

Remove an item at the given position.

Declaration
public void RemoveAt(int index)
Parameters
Type Name Description
System.Int32 index

Zero based index of an item to remove.
Exceptions
Type Condition
System.ArgumentOutOfRangeException

If index is less than 0 or greater than Count
System.InvalidOperationException

If the parent object of the DatabaseArray<T> has been deleted or abandoned.
System.ObjectDisposedException

If the parent object of the DatabaseArray<T> has been disposed.

Implements

System.Collections.Generic.IList<>
System.Collections.Generic.ICollection<>
System.Collections.Generic.IEnumerable<>
System.Collections.IEnumerable

See Also