Class CollectionExtensions

A set of extensions methods exposing notification-related functionality over collections.

Inheritance

object

CollectionExtensions

Namespace: Realms

Assembly: Realm.dll

Syntax

public static class CollectionExtensions

Methods

AsRealmCollection<T>(IDictionary<string, T>)

A convenience method that casts IDictionary<TKey,TValue> to IRealmCollection<T> which implements INotifyCollectionChanged.

Declaration

public static IRealmCollection<KeyValuePair<string, T>> AsRealmCollection<T>(this IDictionary<string, T> dictionary)

Parameters

Type	Name	Description
IDictionary<string, T>	dictionary	The IDictionary<TKey,TValue> to observe for changes.

Returns

Type	Description
IRealmCollection<KeyValuePair<string, T>>	The collection, implementing INotifyCollectionChanged.

Type Parameters

Name	Description
T	Type of the elements in the dictionary.

See Also

SubscribeForNotifications(NotificationCallbackDelegate<T>)

AsRealmCollection<T>(IList<T>)

A convenience method that casts IList<T> to IRealmCollection<T> which implements INotifyCollectionChanged.

Declaration

public static IRealmCollection<T> AsRealmCollection<T>(this IList<T> list)

Parameters

Type	Name	Description
IList<T>	list	The IList<T> to observe for changes.

Returns

Type	Description
IRealmCollection<T>	The collection, implementing INotifyCollectionChanged.

Type Parameters

Name	Description
T	Type of the elements in the list.

See Also

SubscribeForNotifications(NotificationCallbackDelegate<T>)

AsRealmCollection<T>(ISet<T>)

A convenience method that casts ISet<T> to IRealmCollection<T> which implements INotifyCollectionChanged.

Declaration

public static IRealmCollection<T> AsRealmCollection<T>(this ISet<T> set)

Parameters

Type	Name	Description
ISet<T>	set	The ISet<T> to observe for changes.

Returns

Type	Description
IRealmCollection<T>	The collection, implementing INotifyCollectionChanged.

Type Parameters

Name	Description
T	Type of the elements in the set.

See Also

SubscribeForNotifications(NotificationCallbackDelegate<T>)

AsRealmCollection<T>(IQueryable<T>)

A convenience method that casts IQueryable<T> to IRealmCollection<T> which implements INotifyCollectionChanged.

Declaration

public static IRealmCollection<T> AsRealmCollection<T>(this IQueryable<T> query) where T : IRealmObjectBase?

Parameters

Type	Name	Description
IQueryable<T>	query	The IQueryable<T> to observe for changes.

Returns

Type	Description
IRealmCollection<T>	The collection, implementing INotifyCollectionChanged.

Type Parameters

Name	Description
T	Type of the RealmObject or EmbeddedObject in the results.

See Also

SubscribeForNotifications(NotificationCallbackDelegate<T>)

AsRealmQueryable<T>(IDictionary<string, T?>)

Converts a Realm-backed IDictionary<TKey,TValue> to a Realm-backed IQueryable<T> of dictionary's values.

Declaration

public static IQueryable<T> AsRealmQueryable<T>(this IDictionary<string, T?> dictionary) where T : IRealmObjectBase

Parameters

Type	Name	Description
IDictionary<string, T>	dictionary	The dictionary of objects as obtained from a to-many relationship property.

Returns

Type	Description
IQueryable<T>	A queryable collection that represents the values contained in the dictionary.

Type Parameters

Name	Description
T	The type of the values contained in the dictionary.

Remarks

This method works differently from AsQueryable(IEnumerable) in that it only returns a collection of values, not a collection of KeyValuePair<TKey,TValue> and it actually creates an underlying Realm query that represents the dictionary's values. This means that all LINQ methods will be executed by the database and also that you can subscribe for notifications even after applying LINQ filters or ordering.

Examples

var query = owner.DictOfDogs.AsRealmQueryable()
                .Where(d => d.Age > 3)
                .OrderBy(d => d.Name);

var token = query.SubscribeForNotifications((sender, changes, error) =>
{
    // You'll be notified only when dogs older than 3 have been added/removed/updated
    // and the sender collection will be ordered by Name
});

Exceptions

Type	Condition
ArgumentException	Thrown if the dictionary is not managed by Realm.

AsRealmQueryable<T>(IList<T>)

Converts a Realm-backed IList<T> to a Realm-backed IQueryable<T>.

Declaration

public static IQueryable<T> AsRealmQueryable<T>(this IList<T> list) where T : IRealmObjectBase

Parameters

Type	Name	Description
IList<T>	list	The list of objects as obtained from a to-many relationship property.

Returns

Type	Description
IQueryable<T>	A queryable collection that represents the objects contained in the list.

Type Parameters

Name	Description
T	The type of the objects contained in the list.

Remarks

This method works differently from AsQueryable(IEnumerable) in that it actually creates an underlying Realm query to represent the list. This means that all LINQ methods will be executed by the database and also that you can subscribe for notifications even after applying LINQ filters or ordering.

Examples

var dogs = owner.Dogs;
var query = dogs.AsRealmQueryable()
                .Where(d => d.Age > 3)
                .OrderBy(d => d.Name);

var token = query.SubscribeForNotifications((sender, changes, error) =>
{
    // You'll be notified only when dogs older than 3 have been added/removed/updated
    // and the sender collection will be ordered by Name
});

Exceptions

Type	Condition
ArgumentException	Thrown if the list is not managed by Realm.

AsRealmQueryable<T>(ISet<T>)

Converts a Realm-backed ISet<T> to a Realm-backed IQueryable<T>.

Declaration

public static IQueryable<T> AsRealmQueryable<T>(this ISet<T> set) where T : IRealmObjectBase

Parameters

Type	Name	Description
ISet<T>	set	The set of objects as obtained from a to-many relationship property.

Returns

Type	Description
IQueryable<T>	A queryable collection that represents the objects contained in the set.

Type Parameters

Name	Description
T	The type of the objects contained in the set.

Remarks

This method works differently from AsQueryable(IEnumerable) in that it actually creates an underlying Realm query to represent the set. This means that all LINQ methods will be executed by the database and also that you can subscribe for notifications even after applying LINQ filters or ordering.

Examples

var dogs = owner.Dogs;
var query = dogs.AsRealmQueryable()
                .Where(d => d.Age > 3)
                .OrderBy(d => d.Name);

var token = query.SubscribeForNotifications((sender, changes, error) =>
{
    // You'll be notified only when dogs older than 3 have been added/removed/updated
    // and the sender collection will be ordered by Name
});

Exceptions

Type	Condition
ArgumentException	Thrown if the list is not managed by Realm.

Filter<T>(IDictionary<string, T?>, string, params QueryArgument[])

Apply an NSPredicate-based filter over dictionary's values. It can be used to create more complex queries, that are currently unsupported by the LINQ provider and supports SORT and DISTINCT clauses in addition to filtering.

Declaration

public static IQueryable<T> Filter<T>(this IDictionary<string, T?> dictionary, string predicate, params QueryArgument[] arguments) where T : IRealmObjectBase

Parameters

Type	Name	Description
IDictionary<string, T>	dictionary	A Realm Dictionary.
string	predicate	The predicate that will be applied.
QueryArgument[]	arguments	Values used for substitution in the predicate. Note that all primitive types are accepted as they are implicitly converted to RealmValue.

Returns

Type	Description
IQueryable<T>	A queryable observable collection of dictionary values that match the predicate.

Type Parameters

Name	Description
T	The type of the dictionary's values that will be filtered.

Remarks

If you're not going to apply additional filters, it's recommended to use AsRealmCollection<T>(IQueryable<T>) after applying the predicate.

Examples

joe.DictOfDogs.Filter("Name BEGINSWITH $0", "R");

See Also

Examples of the NSPredicate syntax

NSPredicate Cheatsheet

Filter<T>(IList<T>, string, params QueryArgument[])

Apply an NSPredicate-based filter over a collection. It can be used to create more complex queries, that are currently unsupported by the LINQ provider and supports SORT and DISTINCT clauses in addition to filtering.

Declaration

public static IQueryable<T> Filter<T>(this IList<T> list, string predicate, params QueryArgument[] arguments) where T : IRealmObjectBase

Parameters

Type	Name	Description
IList<T>	list	A Realm List.
string	predicate	The predicate that will be applied.
QueryArgument[]	arguments	Values used for substitution in the predicate. Note that all primitive types are accepted as they are implicitly converted to RealmValue.

Returns

Type	Description
IQueryable<T>	A queryable observable collection of objects that match the predicate.

Type Parameters

Name	Description
T	The type of the objects that will be filtered.

Remarks

If you're not going to apply additional filters, it's recommended to use AsRealmCollection<T>(IQueryable<T>) after applying the predicate.

Examples

var joe = realm.All<Person>().Single(p => p.Name == "Joe");
joe.dogs.Filter("Name BEGINSWITH $0", "R");

See Also

Examples of the NSPredicate syntax

NSPredicate Cheatsheet

Filter<T>(ISet<T>, string, params QueryArgument[])

Apply an NSPredicate-based filter over a collection. It can be used to create more complex queries, that are currently unsupported by the LINQ provider and supports SORT and DISTINCT clauses in addition to filtering.

Declaration

public static IQueryable<T> Filter<T>(this ISet<T> set, string predicate, params QueryArgument[] arguments) where T : IRealmObjectBase

Parameters

Type	Name	Description
ISet<T>	set	A Realm Set.
string	predicate	The predicate that will be applied.
QueryArgument[]	arguments	Values used for substitution in the predicate. Note that all primitive types are accepted as they are implicitly converted to RealmValue.

Returns

Type	Description
IQueryable<T>	A queryable observable collection of objects that match the predicate.

Type Parameters

Name	Description
T	The type of the objects that will be filtered.

Remarks

If you're not going to apply additional filters, it's recommended to use AsRealmCollection<T>(IQueryable<T>) after applying the predicate.

Examples

var joe = realm.All<Person>().Single(p => p.Name == "Joe");
joe.dogs.Filter("Name BEGINSWITH $0", "R");

See Also

Examples of the NSPredicate syntax

NSPredicate Cheatsheet

Filter<T>(IQueryable<T>, string, params QueryArgument[])

Apply an NSPredicate-based filter over a collection. It can be used to create more complex queries, that are currently unsupported by the LINQ provider and supports SORT and DISTINCT clauses in addition to filtering.

Declaration

public static IQueryable<T> Filter<T>(this IQueryable<T> query, string predicate, params QueryArgument[] arguments)

Parameters

Type	Name	Description
IQueryable<T>	query	A Queryable collection, obtained by calling All<T>().
string	predicate	The predicate that will be applied.
QueryArgument[]	arguments	Values used for substitution in the predicate. Note that all primitive types are accepted as they are implicitly converted to RealmValue.

Returns

Type	Description
IQueryable<T>	A queryable observable collection of objects that match the predicate.

Type Parameters

Name	Description
T	The type of the objects that will be filtered.

Remarks

If you're not going to apply additional filters, it's recommended to use AsRealmCollection<T>(IQueryable<T>) after applying the predicate.

Examples

var results1 = realm.All<Foo>("Bar.IntValue > 0");
var results2 = realm.All<Foo>("Bar.IntValue > 0 SORT(Bar.IntValue ASC Bar.StringValue DESC)");
var results3 = realm.All<Foo>("Bar.IntValue > 0 SORT(Bar.IntValue ASC Bar.StringValue DESC) DISTINCT(Bar.IntValue)");
var results4 = realm.All<Foo>("Bar.IntValue > $0 || (Bar.String == $1 && Bar.Bool == $2)", 5, "small", true);

See Also

Examples of the NSPredicate syntax

NSPredicate Cheatsheet

Move<T>(IList<T>, T, int)

Move the specified item to a new position within the list.

Declaration

public static void Move<T>(this IList<T> list, T item, int index)

Parameters

Type	Name	Description
IList<T>	list	The list where the move should occur.
T	item	The item that will be moved.
int	index	The new position to which the item will be moved.

Type Parameters

Name	Description
T	Type of the objects in the list.

Remarks

This extension method will work for standalone lists as well by calling Remove(T) and then Insert(Int32, T).

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if the index is less than 0 or greater than Count - 1.

Move<T>(IList<T>, int, int)

Move the specified item to a new position within the list.

Declaration

public static void Move<T>(this IList<T> list, int from, int to)

Parameters

Type	Name	Description
IList<T>	list	The list where the move should occur.
int	from	The index of the item that will be moved.
int	to	The new position to which the item will be moved.

Type Parameters

Name	Description
T	Type of the objects in the list.

Remarks

This extension method will work for standalone lists as well by calling RemoveAt(Int32) and then Insert(Int32, T).

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if the index is less than 0 or greater than Count - 1.

SubscribeAsync<T>(IQueryable<T>, SubscriptionOptions?, WaitForSyncMode, CancellationToken?)

Adds a query to the set of active flexible sync subscriptions. The query will be joined via an OR statement with any existing queries for the same type.

Declaration

public static Task<IQueryable<T>> SubscribeAsync<T>(this IQueryable<T> query, SubscriptionOptions? options = null, WaitForSyncMode waitForSync = WaitForSyncMode.FirstTime, CancellationToken? cancellationToken = null) where T : IRealmObject

Parameters

Type	Name	Description
IQueryable<T>	query	The query that will be matched on the server.
SubscriptionOptions	options	The subscription options controlling the name and/or the type of insert that will be performed.
WaitForSyncMode	waitForSync	A parameter controlling when this method should asynchronously wait for the server to send the objects matching the subscription.
CancellationToken?	cancellationToken	An optional cancellation token to cancel waiting for synchronization with the server. Note that cancelling the operation only cancels the wait itself and not the actual subscription, so the subscription will be added even if the task is cancelled. To remove the subscription, you can use Remove<T>(IQueryable<T>, bool).

Returns

Type	Description
Task<IQueryable<T>>	The original query after it has been added to the subscription set.

Type Parameters

Name	Description
T	The type of objects in the query results.

Remarks

Adding a query that already exists is a no-op.
This method is roughly equivalent to calling Add<T>(IQueryable<T>, SubscriptionOptions?) and then WaitForSynchronizationAsync(CancellationToken?).

See Also

SubscriptionSet

SubscribeForKeyNotifications<T>(IDictionary<string, T>, DictionaryNotificationCallbackDelegate<T>)

A convenience method that casts IQueryable<T> to IRealmCollection<T> and subscribes for change notifications.

Declaration

public static IDisposable SubscribeForKeyNotifications<T>(this IDictionary<string, T> dictionary, DictionaryNotificationCallbackDelegate<T> callback)

Parameters

Type	Name	Description
IDictionary<string, T>	dictionary	The IDictionary<TKey,TValue> to observe for changes.
DictionaryNotificationCallbackDelegate<T>	callback	The callback to be invoked with the updated IRealmCollection<T>.

Returns

Type	Description
IDisposable	A subscription token. It must be kept alive for as long as you want to receive change notifications. To stop receiving notifications, call Dispose().

Type Parameters

Name	Description
T	Type of the elements in the dictionary.

See Also

SubscribeForNotifications(NotificationCallbackDelegate<T>)

SubscribeForNotifications<T>(IDictionary<string, T>, NotificationCallbackDelegate<KeyValuePair<string, T>>)

A convenience method that casts IQueryable<T> to IRealmCollection<T> and subscribes for change notifications.

Declaration

public static IDisposable SubscribeForNotifications<T>(this IDictionary<string, T> dictionary, NotificationCallbackDelegate<KeyValuePair<string, T>> callback)

Parameters

Type	Name	Description
IDictionary<string, T>	dictionary	The IDictionary<TKey,TValue> to observe for changes.
NotificationCallbackDelegate<KeyValuePair<string, T>>	callback	The callback to be invoked with the updated IRealmCollection<T>.

Returns

Type	Description
IDisposable	A subscription token. It must be kept alive for as long as you want to receive change notifications. To stop receiving notifications, call Dispose().

Type Parameters

Name	Description
T	Type of the elements in the dictionary.

See Also

SubscribeForNotifications(NotificationCallbackDelegate<T>)

SubscribeForNotifications<T>(IList<T>, NotificationCallbackDelegate<T>)

A convenience method that casts IList<T> to IRealmCollection<T> and subscribes for change notifications.

Declaration

public static IDisposable SubscribeForNotifications<T>(this IList<T> list, NotificationCallbackDelegate<T> callback)

Parameters

Type	Name	Description
IList<T>	list	The IList<T> to observe for changes.
NotificationCallbackDelegate<T>	callback	The callback to be invoked with the updated IRealmCollection<T>.

Returns

Type	Description
IDisposable	A subscription token. It must be kept alive for as long as you want to receive change notifications. To stop receiving notifications, call Dispose().

Type Parameters

Name	Description
T	Type of the elements in the list.

See Also

SubscribeForNotifications(NotificationCallbackDelegate<T>)

SubscribeForNotifications<T>(ISet<T>, NotificationCallbackDelegate<T>)

A convenience method that casts ISet<T> to IRealmCollection<T> and subscribes for change notifications.

Declaration

public static IDisposable SubscribeForNotifications<T>(this ISet<T> set, NotificationCallbackDelegate<T> callback)

Parameters

Type	Name	Description
ISet<T>	set	The ISet<T> to observe for changes.
NotificationCallbackDelegate<T>	callback	The callback to be invoked with the updated IRealmCollection<T>.

Returns

Type	Description
IDisposable	A subscription token. It must be kept alive for as long as you want to receive change notifications. To stop receiving notifications, call Dispose().

Type Parameters

Name	Description
T	Type of the elements in the set.

See Also

SubscribeForNotifications(NotificationCallbackDelegate<T>)

SubscribeForNotifications<T>(IQueryable<T>, NotificationCallbackDelegate<T>)

A convenience method that casts IQueryable<T> to IRealmCollection<T> and subscribes for change notifications.

Declaration

public static IDisposable SubscribeForNotifications<T>(this IQueryable<T> results, NotificationCallbackDelegate<T> callback) where T : IRealmObjectBase?

Parameters

Type	Name	Description
IQueryable<T>	results	The IQueryable<T> to observe for changes.
NotificationCallbackDelegate<T>	callback	The callback to be invoked with the updated IRealmCollection<T>.

Returns

Type	Description
IDisposable	A subscription token. It must be kept alive for as long as you want to receive change notifications. To stop receiving notifications, call Dispose().

Type Parameters

Name	Description
T	Type of the RealmObject or EmbeddedObject in the results.

See Also

SubscribeForNotifications(NotificationCallbackDelegate<T>)