From 77fd4d012f65ad8d82f05792c3e8447262325f81 Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 1 Apr 2020 16:09:51 +0100 Subject: [PATCH 01/17] Add missing docs for System.Collections.Immutable --- .../ImmutableArray.xml | 28 +- .../ImmutableArray`1+Builder.xml | 107 ++++- .../ImmutableArray`1.xml | 326 ++++++++++++-- .../ImmutableDictionary`2+Builder.xml | 333 +++++++++++++-- .../ImmutableDictionary`2+Enumerator.xml | 95 ++++- .../ImmutableDictionary`2.xml | 397 +++++++++++++++--- .../ImmutableHashSet`1+Builder.xml | 149 ++++++- .../ImmutableHashSet`1+Enumerator.xml | 93 +++- .../ImmutableHashSet`1.xml | 50 ++- .../ImmutableInterlocked.xml | 30 +- .../ImmutableList`1+Builder.xml | 174 +++++++- .../ImmutableList`1+Enumerator.xml | 93 +++- .../ImmutableList`1.xml | 142 ++++++- .../ImmutableQueue`1.xml | 2 +- .../ImmutableSortedDictionary`2+Builder.xml | 349 +++++++++++++-- ...ImmutableSortedDictionary`2+Enumerator.xml | 93 +++- .../ImmutableSortedDictionary`2.xml | 397 +++++++++++++++--- .../ImmutableSortedSet`1+Builder.xml | 187 ++++++++- .../ImmutableSortedSet`1+Enumerator.xml | 93 +++- .../ImmutableSortedSet`1.xml | 126 +++++- 20 files changed, 2914 insertions(+), 350 deletions(-) diff --git a/xml/System.Collections.Immutable/ImmutableArray.xml b/xml/System.Collections.Immutable/ImmutableArray.xml index 9745ec29ff4..992b127b90b 100644 --- a/xml/System.Collections.Immutable/ImmutableArray.xml +++ b/xml/System.Collections.Immutable/ImmutableArray.xml @@ -679,12 +679,12 @@ This overload allows helper methods or custom builder classes to efficiently avo - To be added. - To be added. + The type of element stored in the source array. + The type of element to be stored in the target array. The source array to initialize the resulting array with. The function to apply to each element from the source array. Initializes a new instance of the struct. - To be added. + An immutable array that contains the specified items. - To be added. - To be added. + The type of element stored in the source array. + The type of element to be stored in the target array. The source array to initialize the resulting array with. The index of the first element in the source array to include in the resulting array. The number of elements from the source array to include in the resulting array. The function to apply to each element from the source array included in the resulting array. Initializes a new instance of the struct. - To be added. + An immutable array that contains the specified items. - To be added. - To be added. - To be added. + The type of element stored in the source array. + The type of argument to be passed to the selector mapping function. + The type of element to be stored in the target array. The source array to initialize the resulting array with. The function to apply to each element from the source array. An argument to be passed to the selector mapping function. Initializes a new instance of the struct. - To be added. + An immutable array that contains the specified items. - To be added. - To be added. - To be added. + The type of element stored in the source array. + The type of argument to be passed to the selector mapping function. + The type of element to be stored in the target array. The source array to initialize the resulting array with. The index of the first element in the source array to include in the resulting array. The number of elements from the source array to include in the resulting array. The function to apply to each element from the source array included in the resulting array. An argument to be passed to the selector mapping function. Initializes a new instance of the struct. - To be added. + An immutable array that contains the specified items. + @@ -461,7 +461,15 @@ Removes all items from the array. - To be added. + + must be set to 0, and references to other objects from elements of the collection must be released. + + ]]> + @@ -497,7 +505,15 @@ Determines whether the array contains a specific value. if the object is found; otherwise, . - To be added. + + uses , whereas allows the user to specify the implementation to use for comparing keys. + + ]]> + @@ -611,7 +627,25 @@ Gets an object that can be used to iterate through the collection. An object that can be used to iterate through the collection. - To be added. + + provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. + Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . + returns the same object until is called again as sets to the next element. + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. + An enumerator does not have exclusive access to the collection so an enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection. + Default implementations of collections in the namespace aren't synchronized. + + + ## Examples The following example demonstrates how to implement the interface and uses that implementation to create a LINQ query. When you implement , you must also implement or, for C# only, you can use the [yield](~/docs/csharp/language-reference/keywords/yield.md) keyword. Implementing also requires to be implemented, which you will see in this example. + [!code-csharp[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/cs/program.cs#1)] [!code-vb[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/vb/module1.vb#1)] + For another C# example that demonstrates how to implement the interface, see the [Generics Sample](https://code.msdn.microsoft.com/Generics-Sample-C-9b41a192/sourcecode?fileId=46476&pathId=1364935593). This sample uses of the `yield` keyword instead of implementing . + + ]]> + @@ -646,7 +680,15 @@ The item to locate in the array. Determines the index of a specific item in the array. The index of if it's found in the list; otherwise, -1. - To be added. + + method always returns the first instance found. + + ]]> + @@ -790,7 +832,16 @@ The zero-based index at which to insert the item. The object to insert into the array. Inserts an item in the array at the specified index. - To be added. + + , then `item` is appended to the list. + In collections of contiguous elements, such as lists, the elements that follow the insertion point move down to accommodate the new element. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. + + ]]> + @@ -825,7 +876,16 @@ The index of the item to get or set. Gets or sets the item at the specified index. The item at the specified index. - To be added. + + property. Visual Basic implements as a [default property](~/docs/visual-basic/language-reference/modifiers/default.md), which provides the same indexing functionality. + + ]]> + The specified index is not in the array. @@ -1029,7 +1089,7 @@ Extracts the internal array as an and replaces it with a zero length array. - To be added. + An immutable array containing the elements of the builder. To be added. When doesn't equal . @@ -1067,7 +1127,16 @@ Removes the specified element. if was found and removed; otherwise, . - To be added. + + uses , whereas, allows the user to specify the implementation to use for comparing keys. + In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. + + ]]> + @@ -1101,7 +1170,15 @@ The zero-based index of the item to remove. Removes the item at the specified index from the array. - To be added. + + + @@ -1287,7 +1364,15 @@ Gets a value that indicates whether the is read-only. if the is read-only; otherwise, . - To be added. + + interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. + + ]]> + diff --git a/xml/System.Collections.Immutable/ImmutableArray`1.xml b/xml/System.Collections.Immutable/ImmutableArray`1.xml index 7e2ee3f214d..b54214c907b 100644 --- a/xml/System.Collections.Immutable/ImmutableArray`1.xml +++ b/xml/System.Collections.Immutable/ImmutableArray`1.xml @@ -1,4 +1,4 @@ - + @@ -325,9 +325,9 @@ - To be added. + The type of array element to be returned. Initializes a new instance of the struct by casting the underlying array to an array of type . - To be added. + An ImmutableArray instance with elements cast to the new type. To be added. Thrown if the cast is illegal. @@ -366,10 +366,10 @@ - To be added. + The type of array element to be returned. The array to initialize the array with. No copy is made. - Initializes a new instance of the struct based on the contents of an existing instance, allowing a covariant static cast to efficiently reuse the existing array. - To be added. + Initializes a new instance of the struct based on the contents of an existing instance, allowing a covariant static cast to efficiently reuse the existing array. + An ImmutableArray instance with elements cast to the new type. Determines whether the specified item exists in the array. if the specified item was found in the array; otherwise . - To be added. + + uses , whereas allows the user to specify the implementation to use for comparing keys. + + ]]> + @@ -609,7 +617,29 @@ Indicates whether specified array is equal to this array. if is equal to this array; otherwise, . - To be added. + + method is intended to perform a test for equality with another object of type `T`, the same type as the current object. The method is called in the following circumstances: + - When the `Equals` method is called and the `other` argument is a strongly-typed object of type `T`. (If `other` is not of type `T`, the base method is called. Of the two methods, offers slightly better performance.) + - When the search methods of a number of generic collection objects are called. Some of these types and their methods include the following: + - Some of the generic overloads of the method. + - The search methods of the class, including , , , and . + - The search methods of the class, including and . + - The search methods of the generic class, including and . + In other words, to handle the possibility that objects of a class will be stored in an array or a generic collection object, it is a good idea to implement so that the object can be easily identified and manipulated. + When implementing the method, define equality appropriately for the type specified by the generic type argument. For example, if the type argument is , define equality appropriately for the comparison of two 32-bit signed integers. + + + ## Examples The following example shows the partial implementation of a `Person` class that implements and has two properties, `LastName` and `SSN`. The method returns `True` if the `SSN` property of two `Person` objects is identical; otherwise, it returns `False`. + [!code-csharp[System.GenericIEquatable.Equals#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.GenericIEquatable.Equals/cs/EqualsEx2.cs#3)] [!code-vb[System.GenericIEquatable.Equals#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.GenericIEquatable.Equals/vb/EqualsEx2.vb#3)] + `Person` objects can then be stored in a object and can be identified by the `Contains` method, as the following example shows. + [!code-csharp[System.GenericIEquatable.Equals#12](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.GenericIEquatable.Equals/cs/Snippet12.cs#12)] [!code-vb[System.GenericIEquatable.Equals#12](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.GenericIEquatable.Equals/vb/Snippet12.vb#12)] + + ]]> + @@ -735,7 +765,15 @@ The item to search for. Searches the array for the specified item. The zero-based index position of the item if it is found, or -1 if it is not. - To be added. + + method always returns the first instance found. + + ]]> + @@ -2152,8 +2190,8 @@ System.Int32 - Gets the number of array in the collection. - To be added. + Gets the number of items in the collection. + Number of items in the collection. To be added. Thrown if the property returns true. @@ -2192,7 +2230,15 @@ Gets a value indicating whether this instance is read only. if this instance is read only; otherwise, . - To be added. + + interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. + + ]]> + @@ -2351,7 +2397,16 @@ The zero-based index of the element to get. Gets or sets the element at the specified index in the read-only list. The element at the specified index in the read-only list. - To be added. + + property. Visual Basic implements as a [default property](~/docs/visual-basic/language-reference/modifiers/default.md), which provides the same indexing functionality. + + ]]> + Always thrown from the setter. Thrown if the property returns true. @@ -2387,7 +2442,15 @@ The index. Throws in all cases. - To be added. + + + @@ -2421,8 +2484,8 @@ System.Int32 - Gets the number of array in the collection. - To be added. + Gets the number of items in the collection. + Number of items in the collection. To be added. Thrown if the property returns true. @@ -2540,7 +2603,7 @@ Gets the size of the array. - To be added. + Number of items in the collection. To be added. Thrown if the property returns true. @@ -2576,9 +2639,25 @@ System.Boolean - See the interface. - To be added. - To be added. + See the interface. Always returns since since immutable collections are thread-safe. + Boolean value determining whether the collection is thread-safe. + + instance is cast to an interface. + + + + returns an object, which can be used to synchronize access to the . + Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + @@ -2613,8 +2692,26 @@ Gets the sync root. - To be added. - To be added. + An object for synchronizing access to the collection. + + instance is cast to an interface. + + + + For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: + [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + @@ -2646,7 +2743,29 @@ Returns an enumerator that iterates through the immutable array. An enumerator that iterates through the immutable array. - To be added. + + instance is cast to an interface. + + + + The `foreach` statement of the C# language (`For Each` in Visual Basic) hides the complexity of the enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. + Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. + Initially, the enumerator is positioned before the first element in the collection. The method also brings the enumerator back to this position. At this position, the property is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . + returns the same object until either or is called. sets to the next element. + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returns `false`, is undefined. To set to the first element of the collection again, you can call followed by . + If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + + ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`For Each` in Visual Basic). This code example is part of a larger example for the interface. + [!code-csharp[System.Collections_EnumeratorInterfaces#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#1)] [!code-vb[System.Collections_EnumeratorInterfaces#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#1)] + + ]]> + The property returns . @@ -2682,7 +2801,16 @@ The value to add to the array. Throws in all cases. Throws in all cases. - To be added. + + interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] + + ]]> + Thrown in all cases. @@ -2714,7 +2842,23 @@ Throws in all cases. - To be added. + + instance is cast to an interface. + + + + Implementations of this method can vary in how they handle the and the capacity of a collection. Typically, the count is set to zero, and references to other objects from elements of the collection are also released. The capacity can be set to zero or a default value, or it can remain unchanged. + + + ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] + + ]]> + Thrown in all cases. @@ -2750,7 +2894,19 @@ The value to check for. Throws in all cases. Throws in all cases. - To be added. + + and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. + + + ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] + + ]]> + @@ -2785,7 +2941,19 @@ The value to return the index of. Gets the value at the specified index. The value of the element at the specified index. - To be added. + + and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. + + + ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] + + ]]> + @@ -2821,7 +2989,20 @@ Index that indicates where to insert the item. The value to insert. Throws in all cases. - To be added. + + , then `value` is appended to the end. + In collections of contiguous elements, such as lists, the elements that follow the insertion point move down to accommodate the new element. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. + + + ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] + + ]]> + Thrown in all cases. @@ -2859,7 +3040,23 @@ Gets a value indicating whether this instance is fixed size. if this instance is fixed size; otherwise, . - To be added. + + instance is cast to an interface. + + + + A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements. + + + ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] + + ]]> + @@ -2896,7 +3093,23 @@ Gets a value indicating whether this instance is read only. if this instance is read only; otherwise, . - To be added. + + instance is cast to an interface. + + + + A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. + + + ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] + + ]]> + @@ -2931,7 +3144,20 @@ The index. Gets or sets the at the specified index. The object at the specified index. - To be added. + + property. Visual Basic implements as a default property, which provides the same indexing functionality. + + + ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] + + ]]> + Always thrown from the setter. Thrown if the property returns true. @@ -2967,7 +3193,19 @@ The value to remove from the array. Throws in all cases. - To be added. + + , the remains unchanged and no exception is thrown. + + + ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] + + ]]> + Thrown in all cases. @@ -3002,7 +3240,19 @@ The index of the item to remove. Throws in all cases. - To be added. + + interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] + + ]]> + Thrown in all cases. @@ -3647,7 +3897,15 @@ An object that computes the hash code of the current object. Returns a hash code for the current instance. The hash code for the current instance. - To be added. + + method. + + ]]> + diff --git a/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml b/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml index 6531a541b9a..fbbf13e4f97 100644 --- a/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml @@ -1,4 +1,4 @@ - + @@ -143,7 +143,22 @@ The key of the element to add. The value of the element to add. Adds an element that has the specified key and value to the immutable dictionary. - To be added. + + property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. + Implementations can vary in whether they allow `key` to be `null`. + + + ## Examples The following code example creates an empty of strings, with integer keys, and accesses it through the interface. The code example uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#2](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#2)] [!code-csharp[Generic.IDictionary#2](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#2)] [!code-vb[Generic.IDictionary#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#2)] + + ]]> + is null. An element with the same key already exists in the dictionary. @@ -210,7 +225,15 @@ Removes all items from the immutable dictionary. - To be added. + + must be set to 0, and references to other objects from elements of the collection must be released. + + ]]> + The dictionary is read-only. @@ -247,7 +270,15 @@ Determines whether the immutable dictionary contains a specific value. if is found in the dictionary; otherwise, . - To be added. + + uses , whereas allows the user to specify the implementation to use for comparing keys. + + ]]> + @@ -284,7 +315,21 @@ Determines whether the immutable dictionary contains an element that has the specified key. if the dictionary contains an element with the key; otherwise, . - To be added. + + class uses , whereas the class allows the user to specify the implementation to use for comparing keys. + Implementations can vary in whether they allow `key` to be `null`. + + + ## Examples The following code example shows how to use the method to test whether a key exists prior to calling the method. It also shows how to use the method, which can be a more efficient way to retrieve values if a program frequently tries key values that are not in the dictionary. Finally, it shows how to insert items using property (the indexer in C#). + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#6](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#6)] [!code-csharp[Generic.IDictionary#6](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#6)] [!code-vb[Generic.IDictionary#6](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#6)] [!code-cpp[Generic.IDictionary#5](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#5)] [!code-csharp[Generic.IDictionary#5](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#5)] [!code-vb[Generic.IDictionary#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#5)] [!code-cpp[Generic.IDictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#4)] [!code-csharp[Generic.IDictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#4)] [!code-vb[Generic.IDictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#4)] + + ]]> + is null. @@ -482,7 +527,25 @@ The element to get or set. Gets or sets the element with the specified key. The element that has the specified key. - To be added. + + property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. + The C# language uses the [this](~/docs/csharp/language-reference/keywords/this.md) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. + Implementations can vary in whether they allow `key` to be `null`. + + + ## Examples The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. + The example also shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#3](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#3)] [!code-csharp[Generic.IDictionary#3](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#3)] [!code-vb[Generic.IDictionary#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#3)] [!code-cpp[Generic.IDictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#4)] [!code-csharp[Generic.IDictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#4)] [!code-vb[Generic.IDictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#4)] [!code-cpp[Generic.IDictionary#5](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#5)] [!code-csharp[Generic.IDictionary#5](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#5)] [!code-vb[Generic.IDictionary#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#5)] + + ]]> + is . The property is being retrieved, and is not found. @@ -553,7 +616,15 @@ Gets a collection that contains the keys of the immutable dictionary. A collection that contains the keys of the object that implements the immutable dictionary. - To be added. + + property. + + ]]> + @@ -589,7 +660,16 @@ Removes the first occurrence of a specific object from the immutable dictionary. if was successfully removed from the dictionary; otherwise, . This method also returns false if is not found in the dictionary. - To be added. + + uses , whereas, allows the user to specify the implementation to use for comparing keys. + In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. + + ]]> + The dictionary is read-only. @@ -626,7 +706,20 @@ Removes the element with the specified key from the immutable dictionary. if the element is successfully removed; otherwise, . This method also returns if was not found in the dictionary. - To be added. + + class uses , whereas the class allows the user to specify the implementation to use for comparing keys. + + + ## Examples The following code example shows how to remove a key/value pair from a dictionary using the method. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#10](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#10)] [!code-csharp[Generic.IDictionary#10](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#10)] [!code-vb[Generic.IDictionary#10](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#10)] + + ]]> + is null. The dictionary is read-only. @@ -693,9 +786,9 @@ - To be added. - To be added. - To be added. + The one-dimensional array of type that is the destination of the elements copied from the dictionary. The array must have zero-based indexing. + The zero-based index in at which copying begins. + Copies the elements of the dictionary to an array of type , starting at the specified array index. To be added. @@ -728,7 +821,15 @@ Gets a value that indicates whether the collection is read-only. if the collection is read-only; otherwise, . - To be added. + + interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. + + ]]> + @@ -759,7 +860,20 @@ Gets a collection containing the keys of the generic dictionary. A collection containing the keys of the object that implements the generic dictionary. - To be added. + + is unspecified, but it is guaranteed to be the same order as the corresponding values in the returned by the property. + + + ## Examples The following code example shows how to enumerate keys alone using the property. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#9](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#9)] [!code-csharp[Generic.IDictionary#9](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#9)] [!code-vb[Generic.IDictionary#9](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#9)] + + ]]> + @@ -790,7 +904,20 @@ Gets a collection containing the values in the generic dictionary. A collection containing the values in the object that implements the generic dictionary. - To be added. + + is unspecified, but it is guaranteed to be the same order as the corresponding keys in the returned by the property. + + + ## Examples The following code example shows how to enumerate values alone using the property. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#8](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#8)] [!code-csharp[Generic.IDictionary#8](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#8)] [!code-vb[Generic.IDictionary#8](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#8)] + + ]]> + @@ -822,7 +949,25 @@ Returns an enumerator that iterates through the collection. An enumerator that can be used to iterate through the collection. - To be added. + + provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. + Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . + returns the same object until is called again as sets to the next element. + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. + An enumerator does not have exclusive access to the collection so an enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection. + Default implementations of collections in the namespace aren't synchronized. + + + ## Examples The following example demonstrates how to implement the interface and uses that implementation to create a LINQ query. When you implement , you must also implement or, for C# only, you can use the [yield](~/docs/csharp/language-reference/keywords/yield.md) keyword. Implementing also requires to be implemented, which you will see in this example. + [!code-csharp[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/cs/program.cs#1)] [!code-vb[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/vb/module1.vb#1)] + For another C# example that demonstrates how to implement the interface, see the [Generics Sample](https://code.msdn.microsoft.com/Generics-Sample-C-9b41a192/sourcecode?fileId=46476&pathId=1364935593). This sample uses of the `yield` keyword instead of implementing . + + ]]> + @@ -902,7 +1047,23 @@ Gets a value that indicates whether access to the is synchronized (thread safe). if access to the is synchronized (thread safe); otherwise, . - To be added. + + instance is cast to an interface. + + + + returns an object, which can be used to synchronize access to the . + Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + @@ -938,7 +1099,25 @@ Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . - To be added. + + instance is cast to an interface. + + + + For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: + [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + @@ -1096,7 +1275,24 @@ Gets a value that indicates whether the object has a fixed size. if the object has a fixed size; otherwise, . - To be added. + + instance is cast to an interface. + + + + A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but does allow the modification of existing elements. + A collection with a fixed size is simply a collection with a wrapper that prevents adding and removing elements; therefore, if changes are made to the underlying collection, including the addition or removal of elements, the fixed-size collection reflects those changes. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#6](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#6)] [!code-csharp[Dictionary#6](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#6)] [!code-vb[Dictionary#6](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#6)] + + ]]> + @@ -1128,7 +1324,23 @@ Gets a value that indicates whether the is read-only. if the is read-only; otherwise, . - To be added. + + instance is cast to an interface. + + + + A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#4)] [!code-csharp[Dictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#4)] [!code-vb[Dictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#4)] + + ]]> + @@ -1162,8 +1374,23 @@ The key. Gets or sets the element with the specified key. - To be added. - To be added. + Value stored under specified key. + + property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + Implementations can vary in whether they allow the key to be `null`. + The C# language uses the `this`[this](~/docs/csharp/language-reference/keywords/this.md) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#13](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#13)] [!code-csharp[Dictionary#13](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#13)] [!code-vb[Dictionary#13](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#13)] + + ]]> + @@ -1194,7 +1421,23 @@ Gets an containing the keys of the . An containing the keys of the object that implements . - To be added. + + instance is cast to an interface. + + + + The order of the keys in the returned object is unspecified, but is guaranteed to be the same order as the corresponding values in the returned by the property. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#10](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#10)] [!code-csharp[Dictionary#10](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#10)] [!code-vb[Dictionary#10](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#10)] + + ]]> + @@ -1266,7 +1509,23 @@ Gets an containing the values in the . An containing the values in the object that implements . - To be added. + + instance is cast to an interface. + + + + The order of the values in the returned object is unspecified, but is guaranteed to be the same order as the corresponding keys in the returned by the property. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#11](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#11)] [!code-csharp[Dictionary#11](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#11)] [!code-vb[Dictionary#11](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#11)] + + ]]> + @@ -1428,7 +1687,21 @@ Returns the value associated with the specified key. if the object that implements the immutable dictionary contains an element with the specified key; otherwise, . - To be added. + + method and the property. + If the key is not found, then the `value` parameter gets the appropriate default value for the type `TValue`; for example, zero (0) for integer types, `false` for Boolean types, and `null` for reference types. + + + ## Examples The example shows how to use the method to retrieve values. If a program frequently tries key values that are not in a dictionary, the method can be more efficient than using the property (the indexer in C#), which throws exceptions when attempting to retrieve nonexistent keys. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#5](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#5)] [!code-csharp[Generic.IDictionary#5](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#5)] [!code-vb[Generic.IDictionary#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#5)] [!code-cpp[Generic.IDictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#4)] [!code-csharp[Generic.IDictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#4)] [!code-vb[Generic.IDictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#4)] + + ]]> + is null. @@ -1497,7 +1770,15 @@ Gets a collection that contains the values of the immutable dictionary. A collection that contains the values of the object that implements the dictionary. - To be added. + + property. + + ]]> + diff --git a/xml/System.Collections.Immutable/ImmutableDictionary`2+Enumerator.xml b/xml/System.Collections.Immutable/ImmutableDictionary`2+Enumerator.xml index 2c5ef7e9a18..c7a6036dfab 100644 --- a/xml/System.Collections.Immutable/ImmutableDictionary`2+Enumerator.xml +++ b/xml/System.Collections.Immutable/ImmutableDictionary`2+Enumerator.xml @@ -1,4 +1,4 @@ - + @@ -70,7 +70,19 @@ Gets the element at the current position of the enumerator. The element in the dictionary at the current position of the enumerator. - To be added. + + is undefined under any of the following conditions: + - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . + - The last call to returned `false`, which indicates the end of the collection. + - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. + returns the same object until is called. sets to the next element. + + ]]> + @@ -101,7 +113,29 @@ Releases the resources used by the current instance of the class. - To be added. + + [!WARNING] > If you are using a class that implements the interface, you should call its implementation when you are finished using the class. For more information, see the "Using an object that implements IDisposable" section in the topic. + When implementing this method, ensure that all held resources are freed by propagating the call through the containment hierarchy. For example, if an object A allocates an object B, and object B allocates an object C, then A's implementation must call on B, which must in turn call on C. + > [!IMPORTANT] > The C++ compiler supports deterministic disposal of resources and does not allow direct implementation of the method. + An object must also call the method of its base class if the base class implements . For more information about implementing on a base class and its subclasses, see the "IDisposable and the inheritance hierarchy" section in the topic. + If an object's method is called more than once, the object must ignore all calls after the first one. The object must not throw an exception if its method is called multiple times. Instance methods other than can throw an when resources are already disposed. + Users might expect a resource type to use a particular convention to denote an allocated state versus a freed state. An example of this is stream classes, which are traditionally thought of as open or closed. The implementer of a class that has such a convention might choose to implement a public method with a customized name, such as `Close`, that calls the method. + Because the method must be called explicitly, there is always a danger that the unmanaged resources will not be released, because the consumer of an object fails to call its method. There are two ways to avoid this: + - Wrap the managed resource in an object derived from . Your implementation then calls the method of the instances. For more information, see "The SafeHandle alternative" section in the topic. + - Implement a finalizer to free resources when is not called. By default, the garbage collector automatically calls an object's finalizer before reclaiming its memory. However, if the method has been called, it is typically unnecessary for the garbage collector to call the disposed object's finalizer. To prevent automatic finalization, implementations can call the method. + When you use an object that accesses unmanaged resources, such as a , a good practice is to create the instance with a `using` statement. The `using` statement automatically closes the stream and calls on the object when the code that is using it has completed. For an example, see the class. + + + ## Examples The following example shows how you can implement the method. + [!code-cpp[System.IDisposable.Dispose Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CPP/idisposabledispose.cpp#1)] [!code-csharp[System.IDisposable.Dispose Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CS/idisposabledispose.cs#1)] [!code-vb[System.IDisposable.Dispose Example#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/VB/idisposabledispose.vb#1)] + + ]]> + @@ -134,7 +168,21 @@ Advances the enumerator to the next element of the immutable dictionary. if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the dictionary. - To be added. + + method is called, an enumerator is positioned before the first element of the collection, and the first call to the method moves the enumerator over the first element of the collection. + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false` until is called. + If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of is undefined. + + + ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. + [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] + + ]]> + The dictionary was modified after the enumerator was created. @@ -166,7 +214,20 @@ Sets the enumerator to its initial position, which is before the first element in the dictionary. - To be added. + + is undefined. + The method is provided for COM interoperability. It does not necessarily need to be implemented; instead, the implementer can simply throw a . + + + ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. + [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] + + ]]> + The dictionary was modified after the enumerator was created. @@ -197,8 +258,28 @@ Gets the current element. - To be added. - To be added. + Current element in enumeration. + + instance is cast to an interface. + + + + is undefined under any of the following conditions: + - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . + - The last call to returned `false`, which indicates the end of the collection. + - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. + returns the same object until is called. sets to the next element. + + + ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. + [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] + + ]]> + diff --git a/xml/System.Collections.Immutable/ImmutableDictionary`2.xml b/xml/System.Collections.Immutable/ImmutableDictionary`2.xml index 38452ced7cf..31dc5f587a1 100644 --- a/xml/System.Collections.Immutable/ImmutableDictionary`2.xml +++ b/xml/System.Collections.Immutable/ImmutableDictionary`2.xml @@ -1,4 +1,4 @@ - + @@ -256,7 +256,16 @@ Determines whether the immutable dictionary contains an element with the specified key. if the immutable dictionary contains an element with the specified key; otherwise, . - To be added. + + might use the property, or it might implement the method. + Implementations can vary in whether they allow `key` to be `null`. + + ]]> + @@ -445,7 +454,17 @@ The type of the key. Gets the associated with the specified key. The value associated with the specified key. If no results are found, the operation throws an exception. - To be added. + + might use the property, or it might implement the method. + Implementations can vary in whether they allow `key` to be `null`. + + ]]> + @@ -512,7 +531,15 @@ Gets the keys in the immutable dictionary. The keys in the immutable dictionary. - To be added. + + property. + + ]]> + @@ -681,8 +708,8 @@ - To be added. - To be added. + The object to add to the . + Adds an item to the . To be added. @@ -713,8 +740,16 @@ - To be added. - To be added. + Removes all items from the . + + must be set to 0, and references to other objects from elements of the collection must be released. + + ]]> + @@ -747,9 +782,9 @@ - To be added. - To be added. - To be added. + The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. + The zero-based index in at which copying begins. + Copies the elements of the to an , starting at a particular index. To be added. @@ -779,9 +814,18 @@ System.Boolean - To be added. - To be added. - To be added. + Gets a value indicating whether the is read-only. + + if the is read-only; otherwise, . + + interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. + + ]]> + @@ -813,10 +857,20 @@ - To be added. - To be added. - To be added. - To be added. + The object to remove from the . + Removes the first occurrence of a specific object from the . + + if was successfully removed from the ; otherwise, . This method also returns if is not found in the original . + + uses , whereas, allows the user to specify the implementation to use for comparing keys. + In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. + + ]]> + @@ -852,7 +906,22 @@ The object to use as the key of the element to add. The object to use as the value of the element to add. Adds an element with the provided key and value to the immutable dictionary. - To be added. + + property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. + Implementations can vary in whether they allow `key` to be `null`. + + + ## Examples The following code example creates an empty of strings, with integer keys, and accesses it through the interface. The code example uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#2](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#2)] [!code-csharp[Generic.IDictionary#2](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#2)] [!code-vb[Generic.IDictionary#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#2)] + + ]]> + @@ -887,7 +956,25 @@ The type of the key. Gets or sets the with the specified key. An object of type associated with the . - To be added. + + property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. + The C# language uses the [this](~/docs/csharp/language-reference/keywords/this.md) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. + Implementations can vary in whether they allow `key` to be `null`. + + + ## Examples The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. + The example also shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#3](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#3)] [!code-csharp[Generic.IDictionary#3](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#3)] [!code-vb[Generic.IDictionary#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#3)] [!code-cpp[Generic.IDictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#4)] [!code-csharp[Generic.IDictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#4)] [!code-vb[Generic.IDictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#4)] [!code-cpp[Generic.IDictionary#5](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#5)] [!code-csharp[Generic.IDictionary#5](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#5)] [!code-vb[Generic.IDictionary#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#5)] + + ]]> + @@ -918,7 +1005,20 @@ Gets the keys. A collection containing the keys. - To be added. + + is unspecified, but it is guaranteed to be the same order as the corresponding values in the returned by the property. + + + ## Examples The following code example shows how to enumerate keys alone using the property. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#9](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#9)] [!code-csharp[Generic.IDictionary#9](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#9)] [!code-vb[Generic.IDictionary#9](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#9)] + + ]]> + @@ -954,7 +1054,20 @@ Removes the element with the specified key from the generic dictionary. if the element is successfully removed; otherwise, . This method also returns if was not found in the original generic dictionary. - To be added. + + class uses , whereas the class allows the user to specify the implementation to use for comparing keys. + + + ## Examples The following code example shows how to remove a key/value pair from a dictionary using the method. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#10](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#10)] [!code-csharp[Generic.IDictionary#10](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#10)] [!code-vb[Generic.IDictionary#10](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#10)] + + ]]> + @@ -985,7 +1098,20 @@ Gets the values. A collection containing the values. - To be added. + + is unspecified, but it is guaranteed to be the same order as the corresponding keys in the returned by the property. + + + ## Examples The following code example shows how to enumerate values alone using the property. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#8](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#8)] [!code-csharp[Generic.IDictionary#8](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#8)] [!code-vb[Generic.IDictionary#8](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#8)] + + ]]> + @@ -1017,7 +1143,25 @@ Returns an enumerator that iterates through the collection. An enumerator that can be used to iterate through the collection. - To be added. + + provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. + Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . + returns the same object until is called again as sets to the next element. + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. + An enumerator does not have exclusive access to the collection so an enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection. + Default implementations of collections in the namespace aren't synchronized. + + + ## Examples The following example demonstrates how to implement the interface and uses that implementation to create a LINQ query. When you implement , you must also implement or, for C# only, you can use the [yield](~/docs/csharp/language-reference/keywords/yield.md) keyword. Implementing also requires to be implemented, which you will see in this example. + [!code-csharp[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/cs/program.cs#1)] [!code-vb[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/vb/module1.vb#1)] + For another C# example that demonstrates how to implement the interface, see the [Generics Sample](https://code.msdn.microsoft.com/Generics-Sample-C-9b41a192/sourcecode?fileId=46476&pathId=1364935593). This sample uses of the `yield` keyword instead of implementing . + + ]]> + @@ -1097,7 +1241,23 @@ Gets a value indicating whether access to the is synchronized (thread safe). if access to the is synchronized (thread safe); otherwise, . - To be added. + + instance is cast to an interface. + + + + returns an object, which can be used to synchronize access to the . + Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + @@ -1133,7 +1293,25 @@ Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . - To be added. + + instance is cast to an interface. + + + + For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: + [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + @@ -1329,7 +1507,24 @@ Gets a value indicating whether the object has a fixed size. if the object has a fixed size; otherwise, . - To be added. + + instance is cast to an interface. + + + + A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but does allow the modification of existing elements. + A collection with a fixed size is simply a collection with a wrapper that prevents adding and removing elements; therefore, if changes are made to the underlying collection, including the addition or removal of elements, the fixed-size collection reflects those changes. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#6](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#6)] [!code-csharp[Dictionary#6](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#6)] [!code-vb[Dictionary#6](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#6)] + + ]]> + @@ -1361,7 +1556,23 @@ Gets a value indicating whether the is read-only. if the is read-only; otherwise, . - To be added. + + instance is cast to an interface. + + + + A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#4)] [!code-csharp[Dictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#4)] [!code-vb[Dictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#4)] + + ]]> + @@ -1395,8 +1606,23 @@ The key. Gets or sets the element with the specified key. - To be added. - To be added. + The value stored under the specified key. + + property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + Implementations can vary in whether they allow the key to be `null`. + The C# language uses the `this`[this](~/docs/csharp/language-reference/keywords/this.md) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#13](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#13)] [!code-csharp[Dictionary#13](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#13)] [!code-vb[Dictionary#13](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#13)] + + ]]> + @@ -1427,7 +1653,23 @@ Gets an containing the keys of the . An containing the keys of the object that implements . - To be added. + + instance is cast to an interface. + + + + The order of the keys in the returned object is unspecified, but is guaranteed to be the same order as the corresponding values in the returned by the property. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#10](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#10)] [!code-csharp[Dictionary#10](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#10)] [!code-vb[Dictionary#10](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#10)] + + ]]> + @@ -1499,7 +1741,23 @@ Gets an containing the values in the . An containing the values in the object that implements . - To be added. + + instance is cast to an interface. + + + + The order of the values in the returned object is unspecified, but is guaranteed to be the same order as the corresponding keys in the returned by the property. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#11](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#11)] [!code-csharp[Dictionary#11](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#11)] [!code-vb[Dictionary#11](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#11)] + + ]]> + @@ -1571,11 +1829,19 @@ - To be added. - To be added. - To be added. - To be added. - To be added. + Key of the entry to be added. + Value of the entry to be added. + See the interface + A new immutable dictionary that contains the additional key/value pair. + + + @@ -1607,9 +1873,9 @@ - To be added. - To be added. - To be added. + Sequence of key/value pairs to be added to the dictionary. + See the interface + A new immutable dictionary that contains the additional key/value pairs. To be added. @@ -1674,9 +1940,9 @@ - To be added. - To be added. - To be added. + Key of the entry to be removed. + See the interface + A new immutable dictionary with the specified element removed; or this instance if the specified key cannot be found in the dictionary. To be added. @@ -1709,9 +1975,9 @@ - To be added. - To be added. - To be added. + Sequence of keys to be removed. + See the interface + A new immutable dictionary with the specified keys removed; or this instance if the specified keys cannot be found in the dictionary. To be added. @@ -1745,11 +2011,19 @@ - To be added. - To be added. - To be added. - To be added. - To be added. + Key of entry to be added. + Value of the entry to be added. + See the interface + A new immutable dictionary that contains the specified key/value pair. + + + @@ -1910,7 +2184,16 @@ Gets the value associated with the specified key. if the object that implements the dictionary contains an element with the specified key; otherwise, . - To be added. + + method and the property. + If the key is not found, the `value` parameter gets the appropriate default value for the type `TValue`: for example, 0 (zero) for integer types, `false` for Boolean types, and `null` for reference types. + + ]]> + is null. @@ -1979,7 +2262,15 @@ Gets the values in the immutable dictionary. The values in the immutable dictionary. - To be added. + + property. + + ]]> + diff --git a/xml/System.Collections.Immutable/ImmutableHashSet`1+Builder.xml b/xml/System.Collections.Immutable/ImmutableHashSet`1+Builder.xml index ab2ca32f36d..66c1c8b72e4 100644 --- a/xml/System.Collections.Immutable/ImmutableHashSet`1+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableHashSet`1+Builder.xml @@ -1,4 +1,4 @@ - + @@ -123,7 +123,15 @@ Removes all items from the immutable hash set. - To be added. + + must be set to 0, and references to other objects from elements of the collection must be released. + + ]]> + The hash set is read-only. @@ -160,7 +168,15 @@ Determines whether the immutable hash set contains a specific value. if is found in the hash set ; otherwise, . - To be added. + + uses , whereas allows the user to specify the implementation to use for comparing keys. + + ]]> + @@ -226,7 +242,15 @@ The collection of items to remove from the set. Removes all elements in the specified collection from the current hash set. - To be added. + + + @@ -289,7 +313,15 @@ The collection to compare to the current set. Modifies the current set so that it contains only elements that are also in a specified collection. - To be added. + + + @@ -325,7 +357,17 @@ Determines whether the current set is a proper (strict) subset of a specified collection. if the current set is a proper subset of ; otherwise, . - To be added. + + + @@ -361,7 +403,17 @@ Determines whether the current set is a proper (strict) superset of a specified collection. if the current set is a proper superset of ; otherwise, . - To be added. + + + @@ -397,7 +449,16 @@ Determines whether the current set is a subset of a specified collection. if the current set is a subset of ; otherwise, . - To be added. + + + @@ -433,7 +494,16 @@ Determines whether the current set is a superset of a specified collection. if the current set is a superset of ; otherwise, . - To be added. + + + @@ -497,7 +567,15 @@ Determines whether the current set overlaps with the specified collection. if the current set and share at least one common element; otherwise, . - To be added. + + + @@ -533,7 +611,16 @@ Removes the first occurrence of a specific object from the immutable hash set. if was successfully removed from the set ; otherwise, . This method also returns if is not found in the original set. - To be added. + + uses , whereas, allows the user to specify the implementation to use for comparing keys. + In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. + + ]]> + The set is read-only. @@ -570,7 +657,15 @@ Determines whether the current set and the specified collection contain the same elements. if the current set is equal to ; otherwise, . - To be added. + + + @@ -604,7 +699,15 @@ The collection to compare to the current set. Modifies the current set so that it contains only elements that are present either in the current set or in the specified collection, but not both. - To be added. + + + @@ -721,7 +824,15 @@ Gets a value indicating whether the is read-only. if the is read-only; otherwise, . - To be added. + + interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. + + ]]> + @@ -869,7 +980,15 @@ The collection to compare to the current set. Modifies the current set so that it contains all elements that are present in both the current set and in the specified collection. - To be added. + + + diff --git a/xml/System.Collections.Immutable/ImmutableHashSet`1+Enumerator.xml b/xml/System.Collections.Immutable/ImmutableHashSet`1+Enumerator.xml index 31bfa07b80a..454fd322cba 100644 --- a/xml/System.Collections.Immutable/ImmutableHashSet`1+Enumerator.xml +++ b/xml/System.Collections.Immutable/ImmutableHashSet`1+Enumerator.xml @@ -1,4 +1,4 @@ - + @@ -69,7 +69,19 @@ Gets the element at the current position of the enumerator. The element at the current position of the enumerator. - To be added. + + is undefined under any of the following conditions: + - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . + - The last call to returned `false`, which indicates the end of the collection. + - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. + returns the same object until is called. sets to the next element. + + ]]> + @@ -100,7 +112,29 @@ Releases the resources used by the current instance of the class. - To be added. + + [!WARNING] > If you are using a class that implements the interface, you should call its implementation when you are finished using the class. For more information, see the "Using an object that implements IDisposable" section in the topic. + When implementing this method, ensure that all held resources are freed by propagating the call through the containment hierarchy. For example, if an object A allocates an object B, and object B allocates an object C, then A's implementation must call on B, which must in turn call on C. + > [!IMPORTANT] > The C++ compiler supports deterministic disposal of resources and does not allow direct implementation of the method. + An object must also call the method of its base class if the base class implements . For more information about implementing on a base class and its subclasses, see the "IDisposable and the inheritance hierarchy" section in the topic. + If an object's method is called more than once, the object must ignore all calls after the first one. The object must not throw an exception if its method is called multiple times. Instance methods other than can throw an when resources are already disposed. + Users might expect a resource type to use a particular convention to denote an allocated state versus a freed state. An example of this is stream classes, which are traditionally thought of as open or closed. The implementer of a class that has such a convention might choose to implement a public method with a customized name, such as `Close`, that calls the method. + Because the method must be called explicitly, there is always a danger that the unmanaged resources will not be released, because the consumer of an object fails to call its method. There are two ways to avoid this: + - Wrap the managed resource in an object derived from . Your implementation then calls the method of the instances. For more information, see "The SafeHandle alternative" section in the topic. + - Implement a finalizer to free resources when is not called. By default, the garbage collector automatically calls an object's finalizer before reclaiming its memory. However, if the method has been called, it is typically unnecessary for the garbage collector to call the disposed object's finalizer. To prevent automatic finalization, implementations can call the method. + When you use an object that accesses unmanaged resources, such as a , a good practice is to create the instance with a `using` statement. The `using` statement automatically closes the stream and calls on the object when the code that is using it has completed. For an example, see the class. + + + ## Examples The following example shows how you can implement the method. + [!code-cpp[System.IDisposable.Dispose Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CPP/idisposabledispose.cpp#1)] [!code-csharp[System.IDisposable.Dispose Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CS/idisposabledispose.cs#1)] [!code-vb[System.IDisposable.Dispose Example#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/VB/idisposabledispose.vb#1)] + + ]]> + @@ -133,7 +167,21 @@ Advances the enumerator to the next element of the immutable hash set. if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the hash set. - To be added. + + method is called, an enumerator is positioned before the first element of the collection, and the first call to the method moves the enumerator over the first element of the collection. + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false` until is called. + If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of is undefined. + + + ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. + [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] + + ]]> + The hash set was modified after the enumerator was created. @@ -165,7 +213,20 @@ Sets the enumerator to its initial position, which is before the first element in the hash set. - To be added. + + is undefined. + The method is provided for COM interoperability. It does not necessarily need to be implemented; instead, the implementer can simply throw a . + + + ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. + [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] + + ]]> + The hash set was modified after the enumerator was created. @@ -197,7 +258,27 @@ Gets the current element. To be added. - To be added. + + instance is cast to an interface. + + + + is undefined under any of the following conditions: + - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . + - The last call to returned `false`, which indicates the end of the collection. + - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. + returns the same object until is called. sets to the next element. + + + ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. + [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] + + ]]> + diff --git a/xml/System.Collections.Immutable/ImmutableHashSet`1.xml b/xml/System.Collections.Immutable/ImmutableHashSet`1.xml index 52d22460c35..20427e1c141 100644 --- a/xml/System.Collections.Immutable/ImmutableHashSet`1.xml +++ b/xml/System.Collections.Immutable/ImmutableHashSet`1.xml @@ -1,4 +1,4 @@ - + @@ -826,7 +826,15 @@ See the interface. To be added. - To be added. + + interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. + + ]]> + @@ -1194,7 +1202,23 @@ See the interface. To be added. - To be added. + + instance is cast to an interface. + + + + returns an object, which can be used to synchronize access to the . + Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + @@ -1230,7 +1254,25 @@ See . To be added. - To be added. + + instance is cast to an interface. + + + + For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: + [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + diff --git a/xml/System.Collections.Immutable/ImmutableInterlocked.xml b/xml/System.Collections.Immutable/ImmutableInterlocked.xml index 530432cf8e3..497425c6876 100644 --- a/xml/System.Collections.Immutable/ImmutableInterlocked.xml +++ b/xml/System.Collections.Immutable/ImmutableInterlocked.xml @@ -1,4 +1,4 @@ - + @@ -669,11 +669,13 @@ - To be added. - To be added. - To be added. - To be added. - To be added. + The type of data in the immutable array. + The immutable array to be changed. + A function that produces the new array from the old. This function should be side-effect free, as it may run multiple times when races occur with other threads. + Mutates an immutable array in-place with optimistic locking transaction semantics via a specified transformation function. + The transformation is retried as many times as necessary to win the optimistic locking race. + + if the location's value is changed by applying the result of the function; if the location's value remained the same because the last invocation of returned the existing value. To be added. @@ -745,13 +747,15 @@ - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The type of data in the immutable array. + The type of argument passed to the . + The immutable array to be changed. + A function that produces the new array from the old. This function should be side-effect free, as it may run multiple times when races occur with other threads. + The argument to pass to . + Mutates an immutable array in-place with optimistic locking transaction semantics via a specified transformation function. + The transformation is retried as many times as necessary to win the optimistic locking race. + + if the location's value is changed by applying the result of the function; if the location's value remained the same because the last invocation of returned the existing value. To be added. diff --git a/xml/System.Collections.Immutable/ImmutableList`1+Builder.xml b/xml/System.Collections.Immutable/ImmutableList`1+Builder.xml index 5ef3a0c6773..f5630548700 100644 --- a/xml/System.Collections.Immutable/ImmutableList`1+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableList`1+Builder.xml @@ -1,4 +1,4 @@ - + @@ -312,7 +312,15 @@ Removes all items from the immutable list. - To be added. + + must be set to 0, and references to other objects from elements of the collection must be released. + + ]]> + @@ -348,7 +356,15 @@ Determines whether the immutable list contains a specific value. if item is found in the list; otherwise, . - To be added. + + uses , whereas allows the user to specify the implementation to use for comparing keys. + + ]]> + @@ -1028,7 +1044,15 @@ The object to locate in the immutable list. The value can be for reference types. Searches for the specified object and returns the zero-based index of the first occurrence within the range of elements in the immutable list. The zero-based index of the first occurrence of within the range of elements in the immutable list, if found; otherwise, -1. - To be added. + + method always returns the first instance found. + + ]]> + @@ -1172,7 +1196,16 @@ The zero-based index at which should be inserted. The object to insert into the immutable list. Inserts an item to the immutable list at the specified index. - To be added. + + , then `item` is appended to the list. + In collections of contiguous elements, such as lists, the elements that follow the insertion point move down to accommodate the new element. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. + + ]]> + @@ -1240,7 +1273,16 @@ The index of the item to get or set. Gets or sets the value for a given index in the list. The value at the specified index. - To be added. + + property. Visual Basic implements as a [default property](~/docs/visual-basic/language-reference/modifiers/default.md), which provides the same indexing functionality. + + ]]> + @@ -1449,7 +1491,16 @@ Removes the first occurrence of a specific object from the immutable list. if item was successfully removed from the list; otherwise, . This method also returns if item is not found in the list. - To be added. + + uses , whereas, allows the user to specify the implementation to use for comparing keys. + In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. + + ]]> + @@ -1516,7 +1567,15 @@ The zero-based index of the item to remove from the list. Removes the item at the specified index of the immutable list. - To be added. + + + @@ -1735,7 +1794,15 @@ Gets a value that indicates whether this instance is read-only. Always . - To be added. + + interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. + + ]]> + @@ -1855,7 +1922,23 @@ Gets a value that indicates whether access to the is synchronized (thread safe). if access to the is synchronized (thread safe); otherwise, . - To be added. + + instance is cast to an interface. + + + + returns an object, which can be used to synchronize access to the . + Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + @@ -1891,7 +1974,25 @@ Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . - To be added. + + instance is cast to an interface. + + + + For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: + [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + @@ -2175,7 +2276,23 @@ Gets a value that indicates whether the has a fixed size. if the has a fixed size; otherwise, . - To be added. + + instance is cast to an interface. + + + + A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements. + + + ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] + + ]]> + @@ -2207,7 +2324,23 @@ Gets a value that indicates whether the is read-only. if the is read-only; otherwise, . - To be added. + + instance is cast to an interface. + + + + A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. + + + ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] + + ]]> + @@ -2242,7 +2375,20 @@ The index. Gets or sets the at the specified index. The object at the specified index. - To be added. + + property. Visual Basic implements as a default property, which provides the same indexing functionality. + + + ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] + + ]]> + diff --git a/xml/System.Collections.Immutable/ImmutableList`1+Enumerator.xml b/xml/System.Collections.Immutable/ImmutableList`1+Enumerator.xml index 13c7d380f2a..e254e4b9cb7 100644 --- a/xml/System.Collections.Immutable/ImmutableList`1+Enumerator.xml +++ b/xml/System.Collections.Immutable/ImmutableList`1+Enumerator.xml @@ -1,4 +1,4 @@ - + @@ -84,7 +84,19 @@ Gets the element at the current position of the enumerator. The element at the current position of the enumerator. - To be added. + + is undefined under any of the following conditions: + - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . + - The last call to returned `false`, which indicates the end of the collection. + - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. + returns the same object until is called. sets to the next element. + + ]]> + @@ -115,7 +127,29 @@ Releases the resources used by the current instance of the class. - To be added. + + [!WARNING] > If you are using a class that implements the interface, you should call its implementation when you are finished using the class. For more information, see the "Using an object that implements IDisposable" section in the topic. + When implementing this method, ensure that all held resources are freed by propagating the call through the containment hierarchy. For example, if an object A allocates an object B, and object B allocates an object C, then A's implementation must call on B, which must in turn call on C. + > [!IMPORTANT] > The C++ compiler supports deterministic disposal of resources and does not allow direct implementation of the method. + An object must also call the method of its base class if the base class implements . For more information about implementing on a base class and its subclasses, see the "IDisposable and the inheritance hierarchy" section in the topic. + If an object's method is called more than once, the object must ignore all calls after the first one. The object must not throw an exception if its method is called multiple times. Instance methods other than can throw an when resources are already disposed. + Users might expect a resource type to use a particular convention to denote an allocated state versus a freed state. An example of this is stream classes, which are traditionally thought of as open or closed. The implementer of a class that has such a convention might choose to implement a public method with a customized name, such as `Close`, that calls the method. + Because the method must be called explicitly, there is always a danger that the unmanaged resources will not be released, because the consumer of an object fails to call its method. There are two ways to avoid this: + - Wrap the managed resource in an object derived from . Your implementation then calls the method of the instances. For more information, see "The SafeHandle alternative" section in the topic. + - Implement a finalizer to free resources when is not called. By default, the garbage collector automatically calls an object's finalizer before reclaiming its memory. However, if the method has been called, it is typically unnecessary for the garbage collector to call the disposed object's finalizer. To prevent automatic finalization, implementations can call the method. + When you use an object that accesses unmanaged resources, such as a , a good practice is to create the instance with a `using` statement. The `using` statement automatically closes the stream and calls on the object when the code that is using it has completed. For an example, see the class. + + + ## Examples The following example shows how you can implement the method. + [!code-cpp[System.IDisposable.Dispose Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CPP/idisposabledispose.cpp#1)] [!code-csharp[System.IDisposable.Dispose Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CS/idisposabledispose.cs#1)] [!code-vb[System.IDisposable.Dispose Example#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/VB/idisposabledispose.vb#1)] + + ]]> + @@ -148,7 +182,21 @@ Advances enumeration to the next element of the immutable list. if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the list. - To be added. + + method is called, an enumerator is positioned before the first element of the collection, and the first call to the method moves the enumerator over the first element of the collection. + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false` until is called. + If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of is undefined. + + + ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. + [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] + + ]]> + @@ -179,7 +227,20 @@ Sets the enumerator to its initial position, which is before the first element in the immutable list. - To be added. + + is undefined. + The method is provided for COM interoperability. It does not necessarily need to be implemented; instead, the implementer can simply throw a . + + + ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. + [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] + + ]]> + @@ -210,7 +271,27 @@ The current element. To be added. - To be added. + + instance is cast to an interface. + + + + is undefined under any of the following conditions: + - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . + - The last call to returned `false`, which indicates the end of the collection. + - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. + returns the same object until is called. sets to the next element. + + + ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. + [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] + + ]]> + diff --git a/xml/System.Collections.Immutable/ImmutableList`1.xml b/xml/System.Collections.Immutable/ImmutableList`1.xml index 29ad3045fb8..23d67b8dcca 100644 --- a/xml/System.Collections.Immutable/ImmutableList`1.xml +++ b/xml/System.Collections.Immutable/ImmutableList`1.xml @@ -1,4 +1,4 @@ - + @@ -322,7 +322,15 @@ Determines whether this immutable list contains the specified value. if the list contains the specified value; otherwise, . - To be added. + + uses , whereas allows the user to specify the implementation to use for comparing keys. + + ]]> + @@ -1041,7 +1049,15 @@ The object to locate in the immutable list. The value can be for reference types. Searches for the specified object and returns the zero-based index of the first occurrence within the entire immutable list. The zero-based index of the first occurrence of within the entire immutable list, if found; otherwise, ?1. - To be added. + + method always returns the first instance found. + + ]]> + @@ -1939,7 +1955,15 @@ Gets a value indicating whether the is read-only. if the is read-only; otherwise, . - To be added. + + interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. + + ]]> + @@ -2097,10 +2121,19 @@ - To be added. + The zero-based index of the item to access. Gets or sets the value at the specified index. - To be added. - To be added. + Value stored in the specified index. + + property. Visual Basic implements as a [default property](~/docs/visual-basic/language-reference/modifiers/default.md), which provides the same indexing functionality. + + ]]> + Thrown from getter when is negative or not less than . Always thrown from the setter. @@ -2221,9 +2254,25 @@ System.Boolean - See the interface. - To be added. - To be added. + This type is immutable, so it is always thread-safe. See the interface. + Boolean value determining whether the collection is thread-safe. + + instance is cast to an interface. + + + + returns an object, which can be used to synchronize access to the . + Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + @@ -2258,8 +2307,26 @@ See . - To be added. - To be added. + Object used for synchronizing access to the collection. + + instance is cast to an interface. + + + + For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: + [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + @@ -2543,7 +2610,23 @@ Gets a value indicating whether the has a fixed size. if the has a fixed size; otherwise, . - To be added. + + instance is cast to an interface. + + + + A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements. + + + ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] + + ]]> + @@ -2575,7 +2658,23 @@ Gets a value indicating whether the is read-only. if the is read-only; otherwise, . - To be added. + + instance is cast to an interface. + + + + A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. + + + ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] + + ]]> + @@ -2610,7 +2709,20 @@ The index. Gets or sets the at the specified index. The value at the specified index. - To be added. + + property. Visual Basic implements as a default property, which provides the same indexing functionality. + + + ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] + + ]]> + Thrown from getter when is negative or not less than . Always thrown from the setter. diff --git a/xml/System.Collections.Immutable/ImmutableQueue`1.xml b/xml/System.Collections.Immutable/ImmutableQueue`1.xml index 92edf1b2f05..60ec8409746 100644 --- a/xml/System.Collections.Immutable/ImmutableQueue`1.xml +++ b/xml/System.Collections.Immutable/ImmutableQueue`1.xml @@ -325,7 +325,7 @@ Gets a read-only reference to the element at the front of the queue. - To be added. + Read-only reference to the element at the front of the queue. To be added. The queue is empty. diff --git a/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Builder.xml b/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Builder.xml index 6839f18a622..d95a39d33cf 100644 --- a/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Builder.xml @@ -1,4 +1,4 @@ - + @@ -142,7 +142,22 @@ The key of the element to add. The value of the element to add. Adds an element that has the specified key and value to the immutable sorted dictionary. - To be added. + + property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. + Implementations can vary in whether they allow `key` to be `null`. + + + ## Examples The following code example creates an empty of strings, with integer keys, and accesses it through the interface. The code example uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#2](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#2)] [!code-csharp[Generic.IDictionary#2](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#2)] [!code-vb[Generic.IDictionary#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#2)] + + ]]> + @@ -205,7 +220,15 @@ Removes all items from the immutable sorted dictionary. - To be added. + + must be set to 0, and references to other objects from elements of the collection must be released. + + ]]> + @@ -241,7 +264,15 @@ Determines whether the immutable sorted dictionary contains a specific value. if is found in the dictionary; otherwise, . - To be added. + + uses , whereas allows the user to specify the implementation to use for comparing keys. + + ]]> + @@ -278,7 +309,21 @@ Determines whether the immutable sorted dictionary contains an element with the specified key. if the dictionary contains an element with the key; otherwise, . - To be added. + + class uses , whereas the class allows the user to specify the implementation to use for comparing keys. + Implementations can vary in whether they allow `key` to be `null`. + + + ## Examples The following code example shows how to use the method to test whether a key exists prior to calling the method. It also shows how to use the method, which can be a more efficient way to retrieve values if a program frequently tries key values that are not in the dictionary. Finally, it shows how to insert items using property (the indexer in C#). + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#6](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#6)] [!code-csharp[Generic.IDictionary#6](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#6)] [!code-vb[Generic.IDictionary#6](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#6)] [!code-cpp[Generic.IDictionary#5](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#5)] [!code-csharp[Generic.IDictionary#5](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#5)] [!code-vb[Generic.IDictionary#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#5)] [!code-cpp[Generic.IDictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#4)] [!code-csharp[Generic.IDictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#4)] [!code-vb[Generic.IDictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#4)] + + ]]> + @@ -474,7 +519,25 @@ The key to retrieve the value for. Gets or sets the value for a specified key in the immutable sorted dictionary. The value associated with the given key. - To be added. + + property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. + The C# language uses the [this](~/docs/csharp/language-reference/keywords/this.md) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. + Implementations can vary in whether they allow `key` to be `null`. + + + ## Examples The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. + The example also shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#3](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#3)] [!code-csharp[Generic.IDictionary#3](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#3)] [!code-vb[Generic.IDictionary#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#3)] [!code-cpp[Generic.IDictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#4)] [!code-csharp[Generic.IDictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#4)] [!code-vb[Generic.IDictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#4)] [!code-cpp[Generic.IDictionary#5](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#5)] [!code-csharp[Generic.IDictionary#5](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#5)] [!code-vb[Generic.IDictionary#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#5)] + + ]]> + @@ -533,7 +596,15 @@ Gets a strongly typed, read-only collection of elements. A strongly typed, read-only collection of elements. - To be added. + + property. + + ]]> + @@ -569,7 +640,16 @@ Removes the first occurrence of a specific object from the immutable sorted dictionary. if was successfully removed from the dictionary; otherwise, . This method also returns if is not found in the dictionary. - To be added. + + uses , whereas, allows the user to specify the implementation to use for comparing keys. + In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. + + ]]> + @@ -605,7 +685,20 @@ Removes the element with the specified key from the immutable sorted dictionary. if the element is successfully removed; otherwise, . This method also returns if was not found in the original dictionary. - To be added. + + class uses , whereas the class allows the user to specify the implementation to use for comparing keys. + + + ## Examples The following code example shows how to remove a key/value pair from a dictionary using the method. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#10](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#10)] [!code-csharp[Generic.IDictionary#10](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#10)] [!code-vb[Generic.IDictionary#10](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#10)] + + ]]> + @@ -669,9 +762,9 @@ - To be added. - To be added. - To be added. + The one-dimensional array that is the destination of the elements copied from the dictionary. The array must have zero-based indexing. + The zero-based index in at which copying begins. + See To be added. @@ -703,7 +796,15 @@ Gets a value that indicates whether this instance is read-only. Always . - To be added. + + interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. + + ]]> + @@ -732,9 +833,22 @@ System.Collections.Generic.ICollection<TKey> - To be added. - To be added. - To be added. + Returns a collection containing all keys stored in the dictionary. See + A collection containing all keys stored in the dictionary. + + is unspecified, but it is guaranteed to be the same order as the corresponding values in the returned by the property. + + + ## Examples The following code example shows how to enumerate keys alone using the property. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#9](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#9)] [!code-csharp[Generic.IDictionary#9](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#9)] [!code-vb[Generic.IDictionary#9](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#9)] + + ]]> + @@ -763,9 +877,22 @@ System.Collections.Generic.ICollection<TValue> - To be added. - To be added. - To be added. + Returns a collection containing all values stored in the dictionary. See + A collection containing all values stored in the dictionary. + + is unspecified, but it is guaranteed to be the same order as the corresponding keys in the returned by the property. + + + ## Examples The following code example shows how to enumerate values alone using the property. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#8](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#8)] [!code-csharp[Generic.IDictionary#8](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#8)] [!code-vb[Generic.IDictionary#8](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#8)] + + ]]> + @@ -795,9 +922,27 @@ - To be added. - To be added. - To be added. + See + An enumerator that can be used to iterate through the collection. + + provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. + Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . + returns the same object until is called again as sets to the next element. + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. + An enumerator does not have exclusive access to the collection so an enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection. + Default implementations of collections in the namespace aren't synchronized. + + + ## Examples The following example demonstrates how to implement the interface and uses that implementation to create a LINQ query. When you implement , you must also implement or, for C# only, you can use the [yield](~/docs/csharp/language-reference/keywords/yield.md) keyword. Implementing also requires to be implemented, which you will see in this example. + [!code-csharp[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/cs/program.cs#1)] [!code-vb[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/vb/module1.vb#1)] + For another C# example that demonstrates how to implement the interface, see the [Generics Sample](https://code.msdn.microsoft.com/Generics-Sample-C-9b41a192/sourcecode?fileId=46476&pathId=1364935593). This sample uses of the `yield` keyword instead of implementing . + + ]]> + @@ -879,7 +1024,23 @@ Gets a value that indicates whether access to the is synchronized (thread safe). if access to the is synchronized (thread safe); otherwise, . - To be added. + + instance is cast to an interface. + + + + returns an object, which can be used to synchronize access to the . + Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + @@ -915,7 +1076,25 @@ Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . - To be added. + + instance is cast to an interface. + + + + For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: + [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + @@ -1072,7 +1251,24 @@ Gets a value that indicates whether the object has a fixed size. if the object has a fixed size; otherwise, . - To be added. + + instance is cast to an interface. + + + + A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but does allow the modification of existing elements. + A collection with a fixed size is simply a collection with a wrapper that prevents adding and removing elements; therefore, if changes are made to the underlying collection, including the addition or removal of elements, the fixed-size collection reflects those changes. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#6](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#6)] [!code-csharp[Dictionary#6](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#6)] [!code-vb[Dictionary#6](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#6)] + + ]]> + @@ -1104,7 +1300,23 @@ Gets a value that indicates whether the is read-only. if the is read-only; otherwise, . - To be added. + + instance is cast to an interface. + + + + A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#4)] [!code-csharp[Dictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#4)] [!code-vb[Dictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#4)] + + ]]> + @@ -1138,8 +1350,23 @@ The key. Gets or sets the element with the specified key. - To be added. - To be added. + The value associated with the specified key. + + property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + Implementations can vary in whether they allow the key to be `null`. + The C# language uses the `this`[this](~/docs/csharp/language-reference/keywords/this.md) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#13](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#13)] [!code-csharp[Dictionary#13](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#13)] [!code-vb[Dictionary#13](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#13)] + + ]]> + @@ -1170,7 +1397,23 @@ Gets an containing the keys of the . An containing the keys of the object that implements . - To be added. + + instance is cast to an interface. + + + + The order of the keys in the returned object is unspecified, but is guaranteed to be the same order as the corresponding values in the returned by the property. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#10](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#10)] [!code-csharp[Dictionary#10](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#10)] [!code-vb[Dictionary#10](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#10)] + + ]]> + @@ -1242,7 +1485,23 @@ Gets an containing the values in the . An containing the values in the object that implements . - To be added. + + instance is cast to an interface. + + + + The order of the values in the returned object is unspecified, but is guaranteed to be the same order as the corresponding keys in the returned by the property. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#11](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#11)] [!code-csharp[Dictionary#11](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#11)] [!code-vb[Dictionary#11](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#11)] + + ]]> + @@ -1404,7 +1663,21 @@ Gets the value associated with the specified key. if the object that implements the dictionary contains an element with the specified key; otherwise, . - To be added. + + method and the property. + If the key is not found, then the `value` parameter gets the appropriate default value for the type `TValue`; for example, zero (0) for integer types, `false` for Boolean types, and `null` for reference types. + + + ## Examples The example shows how to use the method to retrieve values. If a program frequently tries key values that are not in a dictionary, the method can be more efficient than using the property (the indexer in C#), which throws exceptions when attempting to retrieve nonexistent keys. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#5](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#5)] [!code-csharp[Generic.IDictionary#5](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#5)] [!code-vb[Generic.IDictionary#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#5)] [!code-cpp[Generic.IDictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#4)] [!code-csharp[Generic.IDictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#4)] [!code-vb[Generic.IDictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#4)] + + ]]> + @@ -1462,9 +1735,9 @@ - To be added. + Key of the entry to be looked up. Returns a read-only reference to the value associated with the provided . - To be added. + A read-only reference to the value associated with the provided . To be added. The is not present. @@ -1497,7 +1770,15 @@ Gets a collection that contains the values of the immutable sorted dictionary. A collection that contains the values of the object that implements the dictionary. - To be added. + + property. + + ]]> + diff --git a/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Enumerator.xml b/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Enumerator.xml index d40a560f099..aca838f6e43 100644 --- a/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Enumerator.xml +++ b/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Enumerator.xml @@ -1,4 +1,4 @@ - + @@ -85,7 +85,19 @@ Gets the element at the current position of the enumerator. The element at the current position of the enumerator. - To be added. + + is undefined under any of the following conditions: + - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . + - The last call to returned `false`, which indicates the end of the collection. + - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. + returns the same object until is called. sets to the next element. + + ]]> + @@ -116,7 +128,29 @@ Releases the resources used by the current instance of the class. - To be added. + + [!WARNING] > If you are using a class that implements the interface, you should call its implementation when you are finished using the class. For more information, see the "Using an object that implements IDisposable" section in the topic. + When implementing this method, ensure that all held resources are freed by propagating the call through the containment hierarchy. For example, if an object A allocates an object B, and object B allocates an object C, then A's implementation must call on B, which must in turn call on C. + > [!IMPORTANT] > The C++ compiler supports deterministic disposal of resources and does not allow direct implementation of the method. + An object must also call the method of its base class if the base class implements . For more information about implementing on a base class and its subclasses, see the "IDisposable and the inheritance hierarchy" section in the topic. + If an object's method is called more than once, the object must ignore all calls after the first one. The object must not throw an exception if its method is called multiple times. Instance methods other than can throw an when resources are already disposed. + Users might expect a resource type to use a particular convention to denote an allocated state versus a freed state. An example of this is stream classes, which are traditionally thought of as open or closed. The implementer of a class that has such a convention might choose to implement a public method with a customized name, such as `Close`, that calls the method. + Because the method must be called explicitly, there is always a danger that the unmanaged resources will not be released, because the consumer of an object fails to call its method. There are two ways to avoid this: + - Wrap the managed resource in an object derived from . Your implementation then calls the method of the instances. For more information, see "The SafeHandle alternative" section in the topic. + - Implement a finalizer to free resources when is not called. By default, the garbage collector automatically calls an object's finalizer before reclaiming its memory. However, if the method has been called, it is typically unnecessary for the garbage collector to call the disposed object's finalizer. To prevent automatic finalization, implementations can call the method. + When you use an object that accesses unmanaged resources, such as a , a good practice is to create the instance with a `using` statement. The `using` statement automatically closes the stream and calls on the object when the code that is using it has completed. For an example, see the class. + + + ## Examples The following example shows how you can implement the method. + [!code-cpp[System.IDisposable.Dispose Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CPP/idisposabledispose.cpp#1)] [!code-csharp[System.IDisposable.Dispose Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CS/idisposabledispose.cs#1)] [!code-vb[System.IDisposable.Dispose Example#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/VB/idisposabledispose.vb#1)] + + ]]> + @@ -149,7 +183,21 @@ Advances the enumerator to the next element of the immutable sorted dictionary. if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the sorted dictionary. - To be added. + + method is called, an enumerator is positioned before the first element of the collection, and the first call to the method moves the enumerator over the first element of the collection. + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false` until is called. + If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of is undefined. + + + ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. + [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] + + ]]> + @@ -180,7 +228,20 @@ Sets the enumerator to its initial position, which is before the first element in the immutable sorted dictionary. - To be added. + + is undefined. + The method is provided for COM interoperability. It does not necessarily need to be implemented; instead, the implementer can simply throw a . + + + ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. + [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] + + ]]> + @@ -211,7 +272,27 @@ The current element. To be added. - To be added. + + instance is cast to an interface. + + + + is undefined under any of the following conditions: + - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . + - The last call to returned `false`, which indicates the end of the collection. + - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. + returns the same object until is called. sets to the next element. + + + ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. + [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] + + ]]> + diff --git a/xml/System.Collections.Immutable/ImmutableSortedDictionary`2.xml b/xml/System.Collections.Immutable/ImmutableSortedDictionary`2.xml index 6d9628081b4..16a63acaeca 100644 --- a/xml/System.Collections.Immutable/ImmutableSortedDictionary`2.xml +++ b/xml/System.Collections.Immutable/ImmutableSortedDictionary`2.xml @@ -1,4 +1,4 @@ - + @@ -249,7 +249,16 @@ Determines whether this immutable sorted map contains the specified key. if the immutable dictionary contains the specified key; otherwise, . - To be added. + + might use the property, or it might implement the method. + Implementations can vary in whether they allow `key` to be `null`. + + ]]> + @@ -435,7 +444,17 @@ The key to retrieve the value for. Gets the associated with the specified key. The value associated with the specified key. If no results are found, the operation throws an exception. - To be added. + + might use the property, or it might implement the method. + Implementations can vary in whether they allow `key` to be `null`. + + ]]> + @@ -494,7 +513,15 @@ Gets the keys in the immutable sorted dictionary. The keys in the immutable dictionary. - To be added. + + property. + + ]]> + @@ -663,8 +690,8 @@ - To be added. - To be added. + The object to add to the . + Adds an item to the . To be added. @@ -695,8 +722,16 @@ - To be added. - To be added. + Removes all items from the . + + must be set to 0, and references to other objects from elements of the collection must be released. + + ]]> + @@ -729,9 +764,9 @@ - To be added. - To be added. - To be added. + The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. + The zero-based index in at which copying begins. + Copies the elements of the to an , starting at a particular index. To be added. @@ -761,9 +796,18 @@ System.Boolean - To be added. - To be added. - To be added. + Gets a value indicating whether the is read-only. + + if the is read-only; otherwise, . + + interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. + + ]]> + @@ -795,10 +839,20 @@ - To be added. - To be added. - To be added. - To be added. + The object to remove from the . + Removes the first occurrence of a specific object from the . + + if was successfully removed from the ; otherwise, . This method also returns if is not found in the original . + + uses , whereas, allows the user to specify the implementation to use for comparing keys. + In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. + + ]]> + @@ -834,7 +888,22 @@ The object to use as the key of the element to add. The object to use as the value of the element to add. Adds an element with the provided key and value to the generic dictionary. - To be added. + + property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. + Implementations can vary in whether they allow `key` to be `null`. + + + ## Examples The following code example creates an empty of strings, with integer keys, and accesses it through the interface. The code example uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#2](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#2)] [!code-csharp[Generic.IDictionary#2](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#2)] [!code-vb[Generic.IDictionary#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#2)] + + ]]> + @@ -866,10 +935,28 @@ - To be added. + The object to use as the key of the element to access. Gets or sets the with the specified key. An object of type associated with the . - To be added. + + property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. + The C# language uses the [this](~/docs/csharp/language-reference/keywords/this.md) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. + Implementations can vary in whether they allow `key` to be `null`. + + + ## Examples The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. + The example also shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#3](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#3)] [!code-csharp[Generic.IDictionary#3](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#3)] [!code-vb[Generic.IDictionary#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#3)] [!code-cpp[Generic.IDictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#4)] [!code-csharp[Generic.IDictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#4)] [!code-vb[Generic.IDictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#4)] [!code-cpp[Generic.IDictionary#5](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#5)] [!code-csharp[Generic.IDictionary#5](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#5)] [!code-vb[Generic.IDictionary#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#5)] + + ]]> + @@ -900,7 +987,20 @@ Gets the keys. A collection containing the keys. - To be added. + + is unspecified, but it is guaranteed to be the same order as the corresponding values in the returned by the property. + + + ## Examples The following code example shows how to enumerate keys alone using the property. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#9](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#9)] [!code-csharp[Generic.IDictionary#9](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#9)] [!code-vb[Generic.IDictionary#9](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#9)] + + ]]> + @@ -936,7 +1036,20 @@ Removes the element with the specified key from the generic dictionary. if the element is successfully removed; otherwise, . This method also returns if was not found in the original generic dictionary. - To be added. + + class uses , whereas the class allows the user to specify the implementation to use for comparing keys. + + + ## Examples The following code example shows how to remove a key/value pair from a dictionary using the method. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#10](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#10)] [!code-csharp[Generic.IDictionary#10](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#10)] [!code-vb[Generic.IDictionary#10](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#10)] + + ]]> + @@ -967,7 +1080,20 @@ Gets the values. A collection containing the values. - To be added. + + is unspecified, but it is guaranteed to be the same order as the corresponding keys in the returned by the property. + + + ## Examples The following code example shows how to enumerate values alone using the property. + This code is part of a larger example that can be compiled and executed. See . + [!code-cpp[Generic.IDictionary#8](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#8)] [!code-csharp[Generic.IDictionary#8](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#8)] [!code-vb[Generic.IDictionary#8](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#8)] + + ]]> + @@ -999,7 +1125,25 @@ Returns an enumerator that iterates through the collection. An enumerator that can be used to iterate through the collection. - To be added. + + provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. + Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . + returns the same object until is called again as sets to the next element. + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. + An enumerator does not have exclusive access to the collection so an enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection. + Default implementations of collections in the namespace aren't synchronized. + + + ## Examples The following example demonstrates how to implement the interface and uses that implementation to create a LINQ query. When you implement , you must also implement or, for C# only, you can use the [yield](~/docs/csharp/language-reference/keywords/yield.md) keyword. Implementing also requires to be implemented, which you will see in this example. + [!code-csharp[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/cs/program.cs#1)] [!code-vb[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/vb/module1.vb#1)] + For another C# example that demonstrates how to implement the interface, see the [Generics Sample](https://code.msdn.microsoft.com/Generics-Sample-C-9b41a192/sourcecode?fileId=46476&pathId=1364935593). This sample uses of the `yield` keyword instead of implementing . + + ]]> + @@ -1079,7 +1223,23 @@ Gets a value indicating whether access to the is synchronized (thread safe). if access to the is synchronized (thread-safe); otherwise, . - To be added. + + instance is cast to an interface. + + + + returns an object, which can be used to synchronize access to the . + Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + @@ -1115,7 +1275,25 @@ Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . - To be added. + + instance is cast to an interface. + + + + For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: + [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + @@ -1311,7 +1489,24 @@ Gets a value indicating whether the object has a fixed size. if the object has a fixed size; otherwise, . - To be added. + + instance is cast to an interface. + + + + A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but does allow the modification of existing elements. + A collection with a fixed size is simply a collection with a wrapper that prevents adding and removing elements; therefore, if changes are made to the underlying collection, including the addition or removal of elements, the fixed-size collection reflects those changes. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#6](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#6)] [!code-csharp[Dictionary#6](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#6)] [!code-vb[Dictionary#6](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#6)] + + ]]> + @@ -1343,7 +1538,23 @@ Gets a value indicating whether the is read-only. if the is read-only; otherwise, . - To be added. + + instance is cast to an interface. + + + + A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#4)] [!code-csharp[Dictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#4)] [!code-vb[Dictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#4)] + + ]]> + @@ -1375,10 +1586,25 @@ - The key. + The key of the element to be accessed. Gets or sets the element with the specified key. - To be added. - To be added. + Value stored under the specified key. + + property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + Implementations can vary in whether they allow the key to be `null`. + The C# language uses the `this`[this](~/docs/csharp/language-reference/keywords/this.md) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#13](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#13)] [!code-csharp[Dictionary#13](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#13)] [!code-vb[Dictionary#13](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#13)] + + ]]> + @@ -1409,7 +1635,23 @@ Gets an containing the keys of the . An containing the keys of the object that implements . - To be added. + + instance is cast to an interface. + + + + The order of the keys in the returned object is unspecified, but is guaranteed to be the same order as the corresponding values in the returned by the property. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#10](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#10)] [!code-csharp[Dictionary#10](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#10)] [!code-vb[Dictionary#10](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#10)] + + ]]> + @@ -1481,7 +1723,23 @@ Gets an containing the values in the . An containing the values in the object that implements . - To be added. + + instance is cast to an interface. + + + + The order of the values in the returned object is unspecified, but is guaranteed to be the same order as the corresponding keys in the returned by the property. + + + ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + [!code-cpp[Dictionary#11](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#11)] [!code-csharp[Dictionary#11](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#11)] [!code-vb[Dictionary#11](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#11)] + + ]]> + @@ -1553,11 +1811,19 @@ - To be added. - To be added. - To be added. + Key of the entry to be added. + Value of the entry to be added. + See the interface. The instance. - To be added. + + + @@ -1589,8 +1855,8 @@ - To be added. - To be added. + Sequence of key/value pairs to be added. + See the interface. The instance. To be added. @@ -1622,7 +1888,7 @@ - To be added. + See the interface. The instance. To be added. @@ -1656,8 +1922,8 @@ - To be added. - To be added. + Key of entry to be removed. + See the interface. The instance. To be added. @@ -1691,8 +1957,8 @@ - To be added. - To be added. + Sequence of keys to be removed. + See the interface. The instance. To be added. @@ -1727,11 +1993,19 @@ - To be added. - To be added. - To be added. + Key of entry to be updated. + Value of entry to be updated. + See the interface. The instance. - To be added. + + + @@ -1892,7 +2166,16 @@ Gets the value associated with the specified key. if the dictionary contains an element with the specified key; otherwise, . - To be added. + + method and the property. + If the key is not found, the `value` parameter gets the appropriate default value for the type `TValue`: for example, 0 (zero) for integer types, `false` for Boolean types, and `null` for reference types. + + ]]> + @@ -1950,9 +2233,9 @@ - To be added. + Key of the entry to be looked up. Returns a read-only reference to the value associated with the provided . - To be added. + A read-only reference to the value associated with the provided . To be added. The is not present. @@ -1985,7 +2268,15 @@ Gets the values in the immutable sorted dictionary. The values in the dictionary. - To be added. + + property. + + ]]> + diff --git a/xml/System.Collections.Immutable/ImmutableSortedSet`1+Builder.xml b/xml/System.Collections.Immutable/ImmutableSortedSet`1+Builder.xml index b4aaf3d5ec5..b19a3ea7c93 100644 --- a/xml/System.Collections.Immutable/ImmutableSortedSet`1+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableSortedSet`1+Builder.xml @@ -1,4 +1,4 @@ - + @@ -129,7 +129,15 @@ Removes all elements from this set. - To be added. + + must be set to 0, and references to other objects from elements of the collection must be released. + + ]]> + @@ -165,7 +173,15 @@ Determines whether the set contains the specified object. if is found in the set; otherwise, . - To be added. + + uses , whereas allows the user to specify the implementation to use for comparing keys. + + ]]> + @@ -232,7 +248,15 @@ The collection of items to remove from the set. Removes the specified set of items from the current set. - To be added. + + + @@ -295,7 +319,15 @@ The collection to compare to the current set. Modifies the current set so that it contains only elements that are also in a specified collection. - To be added. + + + @@ -331,7 +363,17 @@ Determines whether the current set is a proper (strict) subset of a specified collection. if the current set is a proper subset of ; otherwise, . - To be added. + + + @@ -367,7 +409,17 @@ Determines whether the current set is a proper (strict) superset of a specified collection. if the current set is a proper superset of ; otherwise, . - To be added. + + + @@ -403,7 +455,16 @@ Determines whether the current set is a subset of a specified collection. if the current set is a subset of ; otherwise, . - To be added. + + + @@ -439,7 +500,16 @@ Determines whether the current set is a superset of a specified collection. if the current set is a superset of ; otherwise, . - To be added. + + + @@ -638,7 +708,15 @@ Determines whether the current set overlaps with the specified collection. if the current set and share at least one common element; otherwise, . - To be added. + + + @@ -674,7 +752,16 @@ Removes the first occurrence of the specified object from the set. if was removed from the set; if was not found in the set. - To be added. + + uses , whereas, allows the user to specify the implementation to use for comparing keys. + In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. + + ]]> + @@ -739,7 +826,15 @@ Determines whether the current set and the specified collection contain the same elements. if the current set is equal to ; otherwise, . - To be added. + + + @@ -773,7 +868,15 @@ The collection to compare to the current set. Modifies the current set so that it contains only elements that are present either in the current set or in the specified collection, but not both. - To be added. + + + @@ -888,7 +991,15 @@ Gets a value that indicates whether this instance is read-only. Always . - To be added. + + interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. + + ]]> + @@ -1007,7 +1118,23 @@ Gets a value that indicates whether access to the is synchronized (thread-safe). if access to the is synchronized (thread-safe); otherwise, . - To be added. + + instance is cast to an interface. + + + + returns an object, which can be used to synchronize access to the . + Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + @@ -1043,7 +1170,25 @@ Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . - To be added. + + instance is cast to an interface. + + + + For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: + [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + @@ -1152,7 +1297,15 @@ The collection to compare to the current state. Modifies the current set so that it contains all elements that are present in both the current set and in the specified collection. - To be added. + + + diff --git a/xml/System.Collections.Immutable/ImmutableSortedSet`1+Enumerator.xml b/xml/System.Collections.Immutable/ImmutableSortedSet`1+Enumerator.xml index 6e69fe68e2a..828accb1354 100644 --- a/xml/System.Collections.Immutable/ImmutableSortedSet`1+Enumerator.xml +++ b/xml/System.Collections.Immutable/ImmutableSortedSet`1+Enumerator.xml @@ -1,4 +1,4 @@ - + @@ -86,7 +86,19 @@ **NuGet package**: System.Collections.Immutable (about immutable collections and how to install) The element at the current position of the enumerator. - To be added. + + is undefined under any of the following conditions: + - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . + - The last call to returned `false`, which indicates the end of the collection. + - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. + returns the same object until is called. sets to the next element. + + ]]> + @@ -119,7 +131,29 @@ Releases the resources used by the current instance of the class. **NuGet package**: System.Collections.Immutable (about immutable collections and how to install) - To be added. + + [!WARNING] > If you are using a class that implements the interface, you should call its implementation when you are finished using the class. For more information, see the "Using an object that implements IDisposable" section in the topic. + When implementing this method, ensure that all held resources are freed by propagating the call through the containment hierarchy. For example, if an object A allocates an object B, and object B allocates an object C, then A's implementation must call on B, which must in turn call on C. + > [!IMPORTANT] > The C++ compiler supports deterministic disposal of resources and does not allow direct implementation of the method. + An object must also call the method of its base class if the base class implements . For more information about implementing on a base class and its subclasses, see the "IDisposable and the inheritance hierarchy" section in the topic. + If an object's method is called more than once, the object must ignore all calls after the first one. The object must not throw an exception if its method is called multiple times. Instance methods other than can throw an when resources are already disposed. + Users might expect a resource type to use a particular convention to denote an allocated state versus a freed state. An example of this is stream classes, which are traditionally thought of as open or closed. The implementer of a class that has such a convention might choose to implement a public method with a customized name, such as `Close`, that calls the method. + Because the method must be called explicitly, there is always a danger that the unmanaged resources will not be released, because the consumer of an object fails to call its method. There are two ways to avoid this: + - Wrap the managed resource in an object derived from . Your implementation then calls the method of the instances. For more information, see "The SafeHandle alternative" section in the topic. + - Implement a finalizer to free resources when is not called. By default, the garbage collector automatically calls an object's finalizer before reclaiming its memory. However, if the method has been called, it is typically unnecessary for the garbage collector to call the disposed object's finalizer. To prevent automatic finalization, implementations can call the method. + When you use an object that accesses unmanaged resources, such as a , a good practice is to create the instance with a `using` statement. The `using` statement automatically closes the stream and calls on the object when the code that is using it has completed. For an example, see the class. + + + ## Examples The following example shows how you can implement the method. + [!code-cpp[System.IDisposable.Dispose Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CPP/idisposabledispose.cpp#1)] [!code-csharp[System.IDisposable.Dispose Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CS/idisposabledispose.cs#1)] [!code-vb[System.IDisposable.Dispose Example#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/VB/idisposabledispose.vb#1)] + + ]]> + @@ -154,7 +188,21 @@ **NuGet package**: System.Collections.Immutable (about immutable collections and how to install) if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the sorted set. - To be added. + + method is called, an enumerator is positioned before the first element of the collection, and the first call to the method moves the enumerator over the first element of the collection. + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false` until is called. + If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of is undefined. + + + ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. + [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] + + ]]> + @@ -187,7 +235,20 @@ Sets the enumerator to its initial position, which is before the first element in the immutable sorted set. **NuGet package**: System.Collections.Immutable (about immutable collections and how to install) - To be added. + + is undefined. + The method is provided for COM interoperability. It does not necessarily need to be implemented; instead, the implementer can simply throw a . + + + ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. + [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] + + ]]> + @@ -218,7 +279,27 @@ The current element. To be added. - To be added. + + instance is cast to an interface. + + + + is undefined under any of the following conditions: + - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . + - The last call to returned `false`, which indicates the end of the collection. + - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. + returns the same object until is called. sets to the next element. + + + ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. + [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] + + ]]> + diff --git a/xml/System.Collections.Immutable/ImmutableSortedSet`1.xml b/xml/System.Collections.Immutable/ImmutableSortedSet`1.xml index 0a275efe74f..4629e8ea115 100644 --- a/xml/System.Collections.Immutable/ImmutableSortedSet`1.xml +++ b/xml/System.Collections.Immutable/ImmutableSortedSet`1.xml @@ -1,4 +1,4 @@ - + @@ -1261,9 +1261,17 @@ This member is an explicit interface member implementation. It can be used only System.Boolean - See the interface. - To be added. - To be added. + Returns true, since immutable collections are always read-only. See the interface. + A boolean value indicating whether the collection is read-only. + + interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. + + ]]> + @@ -1435,10 +1443,19 @@ This member is an explicit interface member implementation. It can be used only - To be added. + The zero-based index of the item to access. See the interface. - To be added. - To be added. + The element stored at the specified index. + + property. Visual Basic implements as a [default property](~/docs/visual-basic/language-reference/modifiers/default.md), which provides the same indexing functionality. + + ]]> + @@ -1798,9 +1815,25 @@ This member is an explicit interface member implementation. It can be used only System.Boolean - See the interface. - To be added. - To be added. + Returns true, since immutable collections are always thread-safe. See the interface. + A boolean value indicating whether the collection is thread-safe. + + instance is cast to an interface. + + + + returns an object, which can be used to synchronize access to the . + Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + @@ -1835,8 +1868,26 @@ This member is an explicit interface member implementation. It can be used only See . - To be added. - To be added. + Object used for synchronizing access to the collection. + + instance is cast to an interface. + + + + For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: + [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + The following code example shows how to lock the collection using the property during the entire enumeration. + [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] + + ]]> + @@ -2148,7 +2199,23 @@ This member is an explicit interface member implementation. It can be used only Gets a value that indicates whether the has a fixed size. if the has a fixed size; otherwise, . - To be added. + + instance is cast to an interface. + + + + A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements. + + + ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] + + ]]> + @@ -2180,7 +2247,23 @@ This member is an explicit interface member implementation. It can be used only Gets a value that indicates whether the is read-only. if the is read-only; otherwise, . - To be added. + + instance is cast to an interface. + + + + A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. + + + ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] + + ]]> + @@ -2215,7 +2298,20 @@ This member is an explicit interface member implementation. It can be used only The index. Gets or sets the at the specified index. The . - To be added. + + property. Visual Basic implements as a default property, which provides the same indexing functionality. + + + ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] + + ]]> + From cfcc5b5a89e63981e5a165772de0115ca6cb18a9 Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 1 Apr 2020 19:11:52 +0100 Subject: [PATCH 02/17] Update xml/System.Collections.Immutable/ImmutableArray.xml Co-Authored-By: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> --- xml/System.Collections.Immutable/ImmutableArray.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Collections.Immutable/ImmutableArray.xml b/xml/System.Collections.Immutable/ImmutableArray.xml index 992b127b90b..0c7f847395f 100644 --- a/xml/System.Collections.Immutable/ImmutableArray.xml +++ b/xml/System.Collections.Immutable/ImmutableArray.xml @@ -680,7 +680,7 @@ This overload allows helper methods or custom builder classes to efficiently avo The type of element stored in the source array. - The type of element to be stored in the target array. + The type of element to store in the target array. The source array to initialize the resulting array with. The function to apply to each element from the source array. Initializes a new instance of the struct. From 2b99c1412a23c885ccbfcb6a9e5eeae05d124f7d Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 1 Apr 2020 20:20:59 +0100 Subject: [PATCH 03/17] Update xml/System.Collections.Immutable/ImmutableArray.xml Co-Authored-By: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> --- xml/System.Collections.Immutable/ImmutableArray.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Collections.Immutable/ImmutableArray.xml b/xml/System.Collections.Immutable/ImmutableArray.xml index 0c7f847395f..b106d527094 100644 --- a/xml/System.Collections.Immutable/ImmutableArray.xml +++ b/xml/System.Collections.Immutable/ImmutableArray.xml @@ -729,7 +729,7 @@ This overload allows helper methods or custom builder classes to efficiently avo The type of element stored in the source array. - The type of element to be stored in the target array. + The type of element to store in the target array. The source array to initialize the resulting array with. The index of the first element in the source array to include in the resulting array. The number of elements from the source array to include in the resulting array. From b20b9638bbd7c0712962612cfa7ef325bb1de2d2 Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 1 Apr 2020 20:21:10 +0100 Subject: [PATCH 04/17] Update xml/System.Collections.Immutable/ImmutableArray.xml Co-Authored-By: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> --- xml/System.Collections.Immutable/ImmutableArray.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Collections.Immutable/ImmutableArray.xml b/xml/System.Collections.Immutable/ImmutableArray.xml index b106d527094..9d57ddc2995 100644 --- a/xml/System.Collections.Immutable/ImmutableArray.xml +++ b/xml/System.Collections.Immutable/ImmutableArray.xml @@ -781,7 +781,7 @@ This overload allows helper methods or custom builder classes to efficiently avo The type of element stored in the source array. The type of argument to be passed to the selector mapping function. - The type of element to be stored in the target array. + The type of element to store in the target array. The source array to initialize the resulting array with. The function to apply to each element from the source array. An argument to be passed to the selector mapping function. From 1a6811a4cbd202828aac54edcf869910c5c6ebaa Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 1 Apr 2020 20:21:21 +0100 Subject: [PATCH 05/17] Update xml/System.Collections.Immutable/ImmutableArray.xml Co-Authored-By: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> --- xml/System.Collections.Immutable/ImmutableArray.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Collections.Immutable/ImmutableArray.xml b/xml/System.Collections.Immutable/ImmutableArray.xml index 9d57ddc2995..91785a73896 100644 --- a/xml/System.Collections.Immutable/ImmutableArray.xml +++ b/xml/System.Collections.Immutable/ImmutableArray.xml @@ -780,7 +780,7 @@ This overload allows helper methods or custom builder classes to efficiently avo The type of element stored in the source array. - The type of argument to be passed to the selector mapping function. + The type of argument to pass to the selector mapping function. The type of element to store in the target array. The source array to initialize the resulting array with. The function to apply to each element from the source array. From f79251c295a96ab360bfa5b81dfcb139ecbe160f Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 1 Apr 2020 20:21:58 +0100 Subject: [PATCH 06/17] Update xml/System.Collections.Immutable/ImmutableArray`1+Builder.xml Co-Authored-By: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> --- xml/System.Collections.Immutable/ImmutableArray`1+Builder.xml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/xml/System.Collections.Immutable/ImmutableArray`1+Builder.xml b/xml/System.Collections.Immutable/ImmutableArray`1+Builder.xml index b33115f8a46..77ff5e15112 100644 --- a/xml/System.Collections.Immutable/ImmutableArray`1+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableArray`1+Builder.xml @@ -640,7 +640,9 @@ The returned provides the abil Default implementations of collections in the namespace aren't synchronized. - ## Examples The following example demonstrates how to implement the interface and uses that implementation to create a LINQ query. When you implement , you must also implement or, for C# only, you can use the [yield](~/docs/csharp/language-reference/keywords/yield.md) keyword. Implementing also requires to be implemented, which you will see in this example. + ## Examples + + The following example demonstrates how to implement the interface and uses that implementation to create a LINQ query. When you implement , you must also implement or, for C# only, you can use the [yield](~/docs/csharp/language-reference/keywords/yield.md) keyword. Implementing also requires to be implemented, which you will see in this example. [!code-csharp[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/cs/program.cs#1)] [!code-vb[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/vb/module1.vb#1)] For another C# example that demonstrates how to implement the interface, see the [Generics Sample](https://code.msdn.microsoft.com/Generics-Sample-C-9b41a192/sourcecode?fileId=46476&pathId=1364935593). This sample uses of the `yield` keyword instead of implementing . From 5aabf787e640b92db99b783a7d03204f7fae182c Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 1 Apr 2020 20:22:17 +0100 Subject: [PATCH 07/17] Update xml/System.Collections.Immutable/ImmutableArray`1.xml Co-Authored-By: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> --- xml/System.Collections.Immutable/ImmutableArray`1.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Collections.Immutable/ImmutableArray`1.xml b/xml/System.Collections.Immutable/ImmutableArray`1.xml index b54214c907b..520464edbe9 100644 --- a/xml/System.Collections.Immutable/ImmutableArray`1.xml +++ b/xml/System.Collections.Immutable/ImmutableArray`1.xml @@ -325,7 +325,7 @@ - The type of array element to be returned. + The type of array element to return. Initializes a new instance of the struct by casting the underlying array to an array of type . An ImmutableArray instance with elements cast to the new type. To be added. From f9f3613874bc5d94eab0e9ea6ed341946f04c9aa Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 1 Apr 2020 20:22:39 +0100 Subject: [PATCH 08/17] Update xml/System.Collections.Immutable/ImmutableArray`1.xml Co-Authored-By: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> --- xml/System.Collections.Immutable/ImmutableArray`1.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Collections.Immutable/ImmutableArray`1.xml b/xml/System.Collections.Immutable/ImmutableArray`1.xml index 520464edbe9..1404523d814 100644 --- a/xml/System.Collections.Immutable/ImmutableArray`1.xml +++ b/xml/System.Collections.Immutable/ImmutableArray`1.xml @@ -327,7 +327,7 @@ The type of array element to return. Initializes a new instance of the struct by casting the underlying array to an array of type . - An ImmutableArray instance with elements cast to the new type. + An immutable array instance with elements cast to the new type. To be added. Thrown if the cast is illegal. From cf931208fb5abb1877ed26fe0430e436bd1d055c Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 1 Apr 2020 20:22:50 +0100 Subject: [PATCH 09/17] Update xml/System.Collections.Immutable/ImmutableArray`1.xml Co-Authored-By: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> --- xml/System.Collections.Immutable/ImmutableArray`1.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Collections.Immutable/ImmutableArray`1.xml b/xml/System.Collections.Immutable/ImmutableArray`1.xml index 1404523d814..a0fc8aada0a 100644 --- a/xml/System.Collections.Immutable/ImmutableArray`1.xml +++ b/xml/System.Collections.Immutable/ImmutableArray`1.xml @@ -369,7 +369,7 @@ The type of array element to be returned. The array to initialize the array with. No copy is made. Initializes a new instance of the struct based on the contents of an existing instance, allowing a covariant static cast to efficiently reuse the existing array. - An ImmutableArray instance with elements cast to the new type. + An immutable array instance with elements cast to the new type. Date: Wed, 1 Apr 2020 20:23:09 +0100 Subject: [PATCH 10/17] Update xml/System.Collections.Immutable/ImmutableArray`1.xml Co-Authored-By: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> --- xml/System.Collections.Immutable/ImmutableArray`1.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Collections.Immutable/ImmutableArray`1.xml b/xml/System.Collections.Immutable/ImmutableArray`1.xml index a0fc8aada0a..394ac76589c 100644 --- a/xml/System.Collections.Immutable/ImmutableArray`1.xml +++ b/xml/System.Collections.Immutable/ImmutableArray`1.xml @@ -2485,7 +2485,7 @@ In collections of contiguous elements, such as lists, the elements that follow t Gets the number of items in the collection. - Number of items in the collection. + The number of items in the collection. To be added. Thrown if the property returns true. From cb5301a5bed53701735c9594a4c14be55116278f Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 1 Apr 2020 20:23:38 +0100 Subject: [PATCH 11/17] Update xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml Co-Authored-By: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> --- .../ImmutableDictionary`2+Builder.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml b/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml index fbbf13e4f97..10f7de833a3 100644 --- a/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml @@ -786,7 +786,7 @@ Implementations can vary in how they determine equality of objects; for example, - The one-dimensional array of type that is the destination of the elements copied from the dictionary. The array must have zero-based indexing. + The one-dimensional array that is the destination of the elements copied from the dictionary. The array must have zero-based indexing. The zero-based index in at which copying begins. Copies the elements of the dictionary to an array of type , starting at the specified array index. To be added. From 9267e435aa0acf8fbc8efee37f243d509f2ca214 Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 1 Apr 2020 20:31:35 +0100 Subject: [PATCH 12/17] Update xml/System.Collections.Immutable/ImmutableArray`1.xml Co-Authored-By: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> --- xml/System.Collections.Immutable/ImmutableArray`1.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Collections.Immutable/ImmutableArray`1.xml b/xml/System.Collections.Immutable/ImmutableArray`1.xml index 394ac76589c..87c588196b2 100644 --- a/xml/System.Collections.Immutable/ImmutableArray`1.xml +++ b/xml/System.Collections.Immutable/ImmutableArray`1.xml @@ -366,7 +366,7 @@ - The type of array element to be returned. + The type of array element to return. The array to initialize the array with. No copy is made. Initializes a new instance of the struct based on the contents of an existing instance, allowing a covariant static cast to efficiently reuse the existing array. An immutable array instance with elements cast to the new type. From 9939441da5dd299195b56effe6c41c61bbb36c84 Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 1 Apr 2020 20:39:56 +0100 Subject: [PATCH 13/17] Update xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml Co-Authored-By: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> --- .../ImmutableDictionary`2+Builder.xml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml b/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml index 10f7de833a3..f1ebca5670c 100644 --- a/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml @@ -539,7 +539,9 @@ This property provides the ability to access a specific element in the collectio Implementations can vary in whether they allow `key` to be `null`. - ## Examples The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. + ## Examples + + The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. The example also shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary. This code is part of a larger example that can be compiled and executed. See . [!code-cpp[Generic.IDictionary#3](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#3)] [!code-csharp[Generic.IDictionary#3](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#3)] [!code-vb[Generic.IDictionary#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#3)] [!code-cpp[Generic.IDictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#4)] [!code-csharp[Generic.IDictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#4)] [!code-vb[Generic.IDictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#4)] [!code-cpp[Generic.IDictionary#5](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#5)] [!code-csharp[Generic.IDictionary#5](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#5)] [!code-vb[Generic.IDictionary#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#5)] From a984f275d505c0b63ccd4c95c18dd89b2345c975 Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 1 Apr 2020 20:40:05 +0100 Subject: [PATCH 14/17] Update xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml Co-Authored-By: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> --- .../ImmutableDictionary`2+Builder.xml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml b/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml index f1ebca5670c..73adf1b7316 100644 --- a/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml @@ -964,7 +964,9 @@ The returned provides the abil Default implementations of collections in the namespace aren't synchronized. - ## Examples The following example demonstrates how to implement the interface and uses that implementation to create a LINQ query. When you implement , you must also implement or, for C# only, you can use the [yield](~/docs/csharp/language-reference/keywords/yield.md) keyword. Implementing also requires to be implemented, which you will see in this example. + ## Examples + + The following example demonstrates how to implement the interface and uses that implementation to create a LINQ query. When you implement , you must also implement or, for C# only, you can use the [yield](~/docs/csharp/language-reference/keywords/yield.md) keyword. Implementing also requires to be implemented, which you will see in this example. [!code-csharp[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/cs/program.cs#1)] [!code-vb[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/vb/module1.vb#1)] For another C# example that demonstrates how to implement the interface, see the [Generics Sample](https://code.msdn.microsoft.com/Generics-Sample-C-9b41a192/sourcecode?fileId=46476&pathId=1364935593). This sample uses of the `yield` keyword instead of implementing . From 367f2e50c6ac5bbbc1caab6063466ce8b938ead0 Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 1 Apr 2020 20:40:20 +0100 Subject: [PATCH 15/17] Update xml/System.Collections.Immutable/ImmutableArray`1.xml Co-Authored-By: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> --- xml/System.Collections.Immutable/ImmutableArray`1.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Collections.Immutable/ImmutableArray`1.xml b/xml/System.Collections.Immutable/ImmutableArray`1.xml index 87c588196b2..dd1c53ff6ed 100644 --- a/xml/System.Collections.Immutable/ImmutableArray`1.xml +++ b/xml/System.Collections.Immutable/ImmutableArray`1.xml @@ -2603,7 +2603,7 @@ In collections of contiguous elements, such as lists, the elements that follow t Gets the size of the array. - Number of items in the collection. + The number of items in the collection. To be added. Thrown if the property returns true. From 1050914c5392d2363522beffd3787a4069379900 Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 1 Apr 2020 22:03:25 +0100 Subject: [PATCH 16/17] address feedback on remarks --- .../ImmutableArray`1+Builder.xml | 74 +---- .../ImmutableArray`1.xml | 263 ++-------------- .../ImmutableDictionary`2+Builder.xml | 277 +---------------- .../ImmutableDictionary`2+Enumerator.xml | 81 +---- .../ImmutableDictionary`2.xml | 285 ++---------------- .../ImmutableHashSet`1+Builder.xml | 147 +-------- .../ImmutableHashSet`1+Enumerator.xml | 81 +---- .../ImmutableHashSet`1.xml | 28 +- .../ImmutableList`1+Builder.xml | 132 +------- .../ImmutableList`1+Enumerator.xml | 81 +---- .../ImmutableList`1.xml | 90 +----- .../ImmutableSortedDictionary`2+Builder.xml | 263 +--------------- ...ImmutableSortedDictionary`2+Enumerator.xml | 81 +---- .../ImmutableSortedDictionary`2.xml | 285 ++---------------- .../ImmutableSortedSet`1+Builder.xml | 165 +--------- .../ImmutableSortedSet`1+Enumerator.xml | 81 +---- .../ImmutableSortedSet`1.xml | 70 +---- 17 files changed, 156 insertions(+), 2328 deletions(-) diff --git a/xml/System.Collections.Immutable/ImmutableArray`1+Builder.xml b/xml/System.Collections.Immutable/ImmutableArray`1+Builder.xml index 77ff5e15112..76f59161163 100644 --- a/xml/System.Collections.Immutable/ImmutableArray`1+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableArray`1+Builder.xml @@ -461,15 +461,7 @@ Removes all items from the array. - - must be set to 0, and references to other objects from elements of the collection must be released. - - ]]> - + To be added. @@ -505,15 +497,7 @@ Determines whether the array contains a specific value. if the object is found; otherwise, . - - uses , whereas allows the user to specify the implementation to use for comparing keys. - - ]]> - + To be added. @@ -627,27 +611,7 @@ Implementations can vary in how they determine equality of objects; for example, Gets an object that can be used to iterate through the collection. An object that can be used to iterate through the collection. - - provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. - Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . - returns the same object until is called again as sets to the next element. - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. - An enumerator does not have exclusive access to the collection so an enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection. - Default implementations of collections in the namespace aren't synchronized. - - - ## Examples - - The following example demonstrates how to implement the interface and uses that implementation to create a LINQ query. When you implement , you must also implement or, for C# only, you can use the [yield](~/docs/csharp/language-reference/keywords/yield.md) keyword. Implementing also requires to be implemented, which you will see in this example. - [!code-csharp[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/cs/program.cs#1)] [!code-vb[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/vb/module1.vb#1)] - For another C# example that demonstrates how to implement the interface, see the [Generics Sample](https://code.msdn.microsoft.com/Generics-Sample-C-9b41a192/sourcecode?fileId=46476&pathId=1364935593). This sample uses of the `yield` keyword instead of implementing . - - ]]> - + To be added. @@ -682,15 +646,7 @@ The returned provides the abil The item to locate in the array. Determines the index of a specific item in the array. The index of if it's found in the list; otherwise, -1. - - method always returns the first instance found. - - ]]> - + To be added. @@ -834,16 +790,7 @@ If an object occurs multiple times in the list, the The zero-based index at which to insert the item. The object to insert into the array. Inserts an item in the array at the specified index. - - , then `item` is appended to the list. - In collections of contiguous elements, such as lists, the elements that follow the insertion point move down to accommodate the new element. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. - - ]]> - + To be added. @@ -878,16 +825,7 @@ If `index` equals the number of items in the The index of the item to get or set. Gets or sets the item at the specified index. The item at the specified index. - - property. Visual Basic implements as a [default property](~/docs/visual-basic/language-reference/modifiers/default.md), which provides the same indexing functionality. - - ]]> - + To be added. The specified index is not in the array. diff --git a/xml/System.Collections.Immutable/ImmutableArray`1.xml b/xml/System.Collections.Immutable/ImmutableArray`1.xml index dd1c53ff6ed..a66c47414eb 100644 --- a/xml/System.Collections.Immutable/ImmutableArray`1.xml +++ b/xml/System.Collections.Immutable/ImmutableArray`1.xml @@ -442,15 +442,7 @@ Determines whether the specified item exists in the array. if the specified item was found in the array; otherwise . - - uses , whereas allows the user to specify the implementation to use for comparing keys. - - ]]> - + To be added. @@ -617,29 +609,7 @@ Implementations can vary in how they determine equality of objects; for example, Indicates whether specified array is equal to this array. if is equal to this array; otherwise, . - - method is intended to perform a test for equality with another object of type `T`, the same type as the current object. The method is called in the following circumstances: - - When the `Equals` method is called and the `other` argument is a strongly-typed object of type `T`. (If `other` is not of type `T`, the base method is called. Of the two methods, offers slightly better performance.) - - When the search methods of a number of generic collection objects are called. Some of these types and their methods include the following: - - Some of the generic overloads of the method. - - The search methods of the class, including , , , and . - - The search methods of the class, including and . - - The search methods of the generic class, including and . - In other words, to handle the possibility that objects of a class will be stored in an array or a generic collection object, it is a good idea to implement so that the object can be easily identified and manipulated. - When implementing the method, define equality appropriately for the type specified by the generic type argument. For example, if the type argument is , define equality appropriately for the comparison of two 32-bit signed integers. - - - ## Examples The following example shows the partial implementation of a `Person` class that implements and has two properties, `LastName` and `SSN`. The method returns `True` if the `SSN` property of two `Person` objects is identical; otherwise, it returns `False`. - [!code-csharp[System.GenericIEquatable.Equals#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.GenericIEquatable.Equals/cs/EqualsEx2.cs#3)] [!code-vb[System.GenericIEquatable.Equals#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.GenericIEquatable.Equals/vb/EqualsEx2.vb#3)] - `Person` objects can then be stored in a object and can be identified by the `Contains` method, as the following example shows. - [!code-csharp[System.GenericIEquatable.Equals#12](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.GenericIEquatable.Equals/cs/Snippet12.cs#12)] [!code-vb[System.GenericIEquatable.Equals#12](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.GenericIEquatable.Equals/vb/Snippet12.vb#12)] - - ]]> - + To be added. @@ -765,15 +735,7 @@ The implementation of the method is inten The item to search for. Searches the array for the specified item. The zero-based index position of the item if it is found, or -1 if it is not. - - method always returns the first instance found. - - ]]> - + To be added. @@ -2230,15 +2192,7 @@ If an object occurs multiple times in the list, the Gets a value indicating whether this instance is read only. if this instance is read only; otherwise, . - - interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. - - ]]> - + To be added. @@ -2442,15 +2396,7 @@ This property provides the ability to access a specific element in the collectio The index. Throws in all cases. - - - + To be added. @@ -2647,14 +2593,6 @@ In collections of contiguous elements, such as lists, the elements that follow t ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - returns an object, which can be used to synchronize access to the . - Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] ]]> @@ -2693,25 +2631,7 @@ This member is an explicit interface member implementation. It can be used only Gets the sync root. An object for synchronizing access to the collection. - - instance is cast to an interface. - - - - For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. - In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: - [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] - - ]]> - + To be added. @@ -2743,29 +2663,7 @@ This member is an explicit interface member implementation. It can be used only Returns an enumerator that iterates through the immutable array. An enumerator that iterates through the immutable array. - - instance is cast to an interface. - - - - The `foreach` statement of the C# language (`For Each` in Visual Basic) hides the complexity of the enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. - Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. The method also brings the enumerator back to this position. At this position, the property is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . - returns the same object until either or is called. sets to the next element. - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returns `false`, is undefined. To set to the first element of the collection again, you can call followed by . - If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - - ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`For Each` in Visual Basic). This code example is part of a larger example for the interface. - [!code-csharp[System.Collections_EnumeratorInterfaces#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#1)] [!code-vb[System.Collections_EnumeratorInterfaces#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#1)] - - ]]> - + To be added. The property returns . @@ -2801,16 +2699,7 @@ This member is an explicit interface member implementation. It can be used only The value to add to the array. Throws in all cases. Throws in all cases. - - interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] - - ]]> - + To be added. Thrown in all cases. @@ -2842,23 +2731,7 @@ This member is an explicit interface member implementation. It can be used only Throws in all cases. - - instance is cast to an interface. - - - - Implementations of this method can vary in how they handle the and the capacity of a collection. Typically, the count is set to zero, and references to other objects from elements of the collection are also released. The capacity can be set to zero or a default value, or it can remain unchanged. - - - ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] - - ]]> - + To be added. Thrown in all cases. @@ -2894,19 +2767,7 @@ This member is an explicit interface member implementation. It can be used only The value to check for. Throws in all cases. Throws in all cases. - - and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. - - - ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] - - ]]> - + To be added. @@ -2941,19 +2802,7 @@ Starting with the .NET Framework 2.0, this method uses the collection's objects' The value to return the index of. Gets the value at the specified index. The value of the element at the specified index. - - and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. - - - ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] - - ]]> - + To be added. @@ -2989,20 +2838,7 @@ Starting with the .NET Framework 2.0, this method uses the collection's objects' Index that indicates where to insert the item. The value to insert. Throws in all cases. - - , then `value` is appended to the end. - In collections of contiguous elements, such as lists, the elements that follow the insertion point move down to accommodate the new element. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. - - - ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] - - ]]> - + To be added. Thrown in all cases. @@ -3040,23 +2876,7 @@ If `index` equals the number of items in the , th Gets a value indicating whether this instance is fixed size. if this instance is fixed size; otherwise, . - - instance is cast to an interface. - - - - A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements. - - - ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] - - ]]> - + To be added. @@ -3093,23 +2913,7 @@ This member is an explicit interface member implementation. It can be used only Gets a value indicating whether this instance is read only. if this instance is read only; otherwise, . - - instance is cast to an interface. - - - - A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. - - - ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] - - ]]> - + To be added. @@ -3144,20 +2948,7 @@ This member is an explicit interface member implementation. It can be used only The index. Gets or sets the at the specified index. The object at the specified index. - - property. Visual Basic implements as a default property, which provides the same indexing functionality. - - - ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] - - ]]> - + To be added. Always thrown from the setter. Thrown if the property returns true. @@ -3240,19 +3031,7 @@ In collections of contiguous elements, such as lists, the elements that follow t The index of the item to remove. Throws in all cases. - - interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] - - ]]> - + To be added. Thrown in all cases. @@ -3897,15 +3676,7 @@ In collections of contiguous elements, such as lists, the elements that follow t An object that computes the hash code of the current object. Returns a hash code for the current instance. The hash code for the current instance. - - method. - - ]]> - + To be added. diff --git a/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml b/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml index 73adf1b7316..e428dce1b1c 100644 --- a/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml @@ -143,22 +143,7 @@ The key of the element to add. The value of the element to add. Adds an element that has the specified key and value to the immutable dictionary. - - property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. - Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. - Implementations can vary in whether they allow `key` to be `null`. - - - ## Examples The following code example creates an empty of strings, with integer keys, and accesses it through the interface. The code example uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#2](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#2)] [!code-csharp[Generic.IDictionary#2](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#2)] [!code-vb[Generic.IDictionary#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#2)] - - ]]> - + To be added. is null. An element with the same key already exists in the dictionary. @@ -225,15 +210,7 @@ You can also use the p Removes all items from the immutable dictionary. - - must be set to 0, and references to other objects from elements of the collection must be released. - - ]]> - + To be added. The dictionary is read-only. @@ -270,15 +247,7 @@ You can also use the p Determines whether the immutable dictionary contains a specific value. if is found in the dictionary; otherwise, . - - uses , whereas allows the user to specify the implementation to use for comparing keys. - - ]]> - + To be added. @@ -315,21 +284,7 @@ Implementations can vary in how they determine equality of objects; for example, Determines whether the immutable dictionary contains an element that has the specified key. if the dictionary contains an element with the key; otherwise, . - - class uses , whereas the class allows the user to specify the implementation to use for comparing keys. - Implementations can vary in whether they allow `key` to be `null`. - - - ## Examples The following code example shows how to use the method to test whether a key exists prior to calling the method. It also shows how to use the method, which can be a more efficient way to retrieve values if a program frequently tries key values that are not in the dictionary. Finally, it shows how to insert items using property (the indexer in C#). - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#6](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#6)] [!code-csharp[Generic.IDictionary#6](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#6)] [!code-vb[Generic.IDictionary#6](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#6)] [!code-cpp[Generic.IDictionary#5](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#5)] [!code-csharp[Generic.IDictionary#5](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#5)] [!code-vb[Generic.IDictionary#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#5)] [!code-cpp[Generic.IDictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#4)] [!code-csharp[Generic.IDictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#4)] [!code-vb[Generic.IDictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#4)] - - ]]> - + To be added. is null. @@ -527,27 +482,7 @@ Implementations can vary in how they determine equality of objects; for example, The element to get or set. Gets or sets the element with the specified key. The element that has the specified key. - - property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. - Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. - The C# language uses the [this](~/docs/csharp/language-reference/keywords/this.md) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. - Implementations can vary in whether they allow `key` to be `null`. - - - ## Examples - - The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. - The example also shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#3](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#3)] [!code-csharp[Generic.IDictionary#3](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#3)] [!code-vb[Generic.IDictionary#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#3)] [!code-cpp[Generic.IDictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#4)] [!code-csharp[Generic.IDictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#4)] [!code-vb[Generic.IDictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#4)] [!code-cpp[Generic.IDictionary#5](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#5)] [!code-csharp[Generic.IDictionary#5](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#5)] [!code-vb[Generic.IDictionary#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#5)] - - ]]> - + To be added. is . The property is being retrieved, and is not found. @@ -618,15 +553,7 @@ This property provides the ability to access a specific element in the collectio Gets a collection that contains the keys of the immutable dictionary. A collection that contains the keys of the object that implements the immutable dictionary. - - property. - - ]]> - + To be added. @@ -662,16 +589,7 @@ The order of the keys in the enumerable collection is unspecified, but the imple Removes the first occurrence of a specific object from the immutable dictionary. if was successfully removed from the dictionary; otherwise, . This method also returns false if is not found in the dictionary. - - uses , whereas, allows the user to specify the implementation to use for comparing keys. - In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. - - ]]> - + To be added. The dictionary is read-only. @@ -708,20 +626,7 @@ Implementations can vary in how they determine equality of objects; for example, Removes the element with the specified key from the immutable dictionary. if the element is successfully removed; otherwise, . This method also returns if was not found in the dictionary. - - class uses , whereas the class allows the user to specify the implementation to use for comparing keys. - - - ## Examples The following code example shows how to remove a key/value pair from a dictionary using the method. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#10](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#10)] [!code-csharp[Generic.IDictionary#10](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#10)] [!code-vb[Generic.IDictionary#10](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#10)] - - ]]> - + To be added. is null. The dictionary is read-only. @@ -823,15 +728,7 @@ Implementations can vary in how they determine equality of objects; for example, Gets a value that indicates whether the collection is read-only. if the collection is read-only; otherwise, . - - interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. - - ]]> - + To be added. @@ -862,20 +759,7 @@ A collection that is read-only does not allow the addition or removal of element Gets a collection containing the keys of the generic dictionary. A collection containing the keys of the object that implements the generic dictionary. - - is unspecified, but it is guaranteed to be the same order as the corresponding values in the returned by the property. - - - ## Examples The following code example shows how to enumerate keys alone using the property. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#9](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#9)] [!code-csharp[Generic.IDictionary#9](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#9)] [!code-vb[Generic.IDictionary#9](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#9)] - - ]]> - + To be added. @@ -906,20 +790,7 @@ The order of the keys in the returned Gets a collection containing the values in the generic dictionary. A collection containing the values in the object that implements the generic dictionary. - - is unspecified, but it is guaranteed to be the same order as the corresponding keys in the returned by the property. - - - ## Examples The following code example shows how to enumerate values alone using the property. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#8](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#8)] [!code-csharp[Generic.IDictionary#8](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#8)] [!code-vb[Generic.IDictionary#8](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#8)] - - ]]> - + To be added. @@ -951,27 +822,7 @@ The order of the values in the returned Returns an enumerator that iterates through the collection. An enumerator that can be used to iterate through the collection. - - provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. - Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . - returns the same object until is called again as sets to the next element. - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. - An enumerator does not have exclusive access to the collection so an enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection. - Default implementations of collections in the namespace aren't synchronized. - - - ## Examples - - The following example demonstrates how to implement the interface and uses that implementation to create a LINQ query. When you implement , you must also implement or, for C# only, you can use the [yield](~/docs/csharp/language-reference/keywords/yield.md) keyword. Implementing also requires to be implemented, which you will see in this example. - [!code-csharp[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/cs/program.cs#1)] [!code-vb[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/vb/module1.vb#1)] - For another C# example that demonstrates how to implement the interface, see the [Generics Sample](https://code.msdn.microsoft.com/Generics-Sample-C-9b41a192/sourcecode?fileId=46476&pathId=1364935593). This sample uses of the `yield` keyword instead of implementing . - - ]]> - + To be added. @@ -1057,14 +908,6 @@ The returned provides the abil ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - returns an object, which can be used to synchronize access to the . - Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] ]]> @@ -1109,16 +952,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. - In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: - [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] ]]> @@ -1285,15 +1118,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but does allow the modification of existing elements. - A collection with a fixed size is simply a collection with a wrapper that prevents adding and removing elements; therefore, if changes are made to the underlying collection, including the addition or removal of elements, the fixed-size collection reflects those changes. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#6](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#6)] [!code-csharp[Dictionary#6](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#6)] [!code-vb[Dictionary#6](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#6)] ]]> @@ -1334,14 +1158,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#4)] [!code-csharp[Dictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#4)] [!code-vb[Dictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#4)] ]]> @@ -1379,22 +1195,7 @@ This member is an explicit interface member implementation. It can be used only The key. Gets or sets the element with the specified key. Value stored under specified key. - - property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. - Implementations can vary in whether they allow the key to be `null`. - The C# language uses the `this`[this](~/docs/csharp/language-reference/keywords/this.md) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#13](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#13)] [!code-csharp[Dictionary#13](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#13)] [!code-vb[Dictionary#13](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#13)] - - ]]> - + To be added. @@ -1431,14 +1232,6 @@ This property provides the ability to access a specific element in the collectio ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - The order of the keys in the returned object is unspecified, but is guaranteed to be the same order as the corresponding values in the returned by the property. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#10](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#10)] [!code-csharp[Dictionary#10](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#10)] [!code-vb[Dictionary#10](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#10)] ]]> @@ -1513,23 +1306,7 @@ This member is an explicit interface member implementation. It can be used only Gets an containing the values in the . An containing the values in the object that implements . - - instance is cast to an interface. - - - - The order of the values in the returned object is unspecified, but is guaranteed to be the same order as the corresponding keys in the returned by the property. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#11](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#11)] [!code-csharp[Dictionary#11](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#11)] [!code-vb[Dictionary#11](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#11)] - - ]]> - + To be added. @@ -1691,21 +1468,7 @@ This member is an explicit interface member implementation. It can be used only Returns the value associated with the specified key. if the object that implements the immutable dictionary contains an element with the specified key; otherwise, . - - method and the property. - If the key is not found, then the `value` parameter gets the appropriate default value for the type `TValue`; for example, zero (0) for integer types, `false` for Boolean types, and `null` for reference types. - - - ## Examples The example shows how to use the method to retrieve values. If a program frequently tries key values that are not in a dictionary, the method can be more efficient than using the property (the indexer in C#), which throws exceptions when attempting to retrieve nonexistent keys. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#5](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#5)] [!code-csharp[Generic.IDictionary#5](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#5)] [!code-vb[Generic.IDictionary#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#5)] [!code-cpp[Generic.IDictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#4)] [!code-csharp[Generic.IDictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#4)] [!code-vb[Generic.IDictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#4)] - - ]]> - + To be added. is null. @@ -1774,15 +1537,7 @@ This method combines the functionality of the Gets a collection that contains the values of the immutable dictionary. A collection that contains the values of the object that implements the dictionary. - - property. - - ]]> - + To be added. diff --git a/xml/System.Collections.Immutable/ImmutableDictionary`2+Enumerator.xml b/xml/System.Collections.Immutable/ImmutableDictionary`2+Enumerator.xml index c7a6036dfab..4a89217e68c 100644 --- a/xml/System.Collections.Immutable/ImmutableDictionary`2+Enumerator.xml +++ b/xml/System.Collections.Immutable/ImmutableDictionary`2+Enumerator.xml @@ -70,19 +70,7 @@ Gets the element at the current position of the enumerator. The element in the dictionary at the current position of the enumerator. - - is undefined under any of the following conditions: - - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . - - The last call to returned `false`, which indicates the end of the collection. - - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - returns the same object until is called. sets to the next element. - - ]]> - + To be added. @@ -113,29 +101,7 @@ Releases the resources used by the current instance of the class. - - [!WARNING] > If you are using a class that implements the interface, you should call its implementation when you are finished using the class. For more information, see the "Using an object that implements IDisposable" section in the topic. - When implementing this method, ensure that all held resources are freed by propagating the call through the containment hierarchy. For example, if an object A allocates an object B, and object B allocates an object C, then A's implementation must call on B, which must in turn call on C. - > [!IMPORTANT] > The C++ compiler supports deterministic disposal of resources and does not allow direct implementation of the method. - An object must also call the method of its base class if the base class implements . For more information about implementing on a base class and its subclasses, see the "IDisposable and the inheritance hierarchy" section in the topic. - If an object's method is called more than once, the object must ignore all calls after the first one. The object must not throw an exception if its method is called multiple times. Instance methods other than can throw an when resources are already disposed. - Users might expect a resource type to use a particular convention to denote an allocated state versus a freed state. An example of this is stream classes, which are traditionally thought of as open or closed. The implementer of a class that has such a convention might choose to implement a public method with a customized name, such as `Close`, that calls the method. - Because the method must be called explicitly, there is always a danger that the unmanaged resources will not be released, because the consumer of an object fails to call its method. There are two ways to avoid this: - - Wrap the managed resource in an object derived from . Your implementation then calls the method of the instances. For more information, see "The SafeHandle alternative" section in the topic. - - Implement a finalizer to free resources when is not called. By default, the garbage collector automatically calls an object's finalizer before reclaiming its memory. However, if the method has been called, it is typically unnecessary for the garbage collector to call the disposed object's finalizer. To prevent automatic finalization, implementations can call the method. - When you use an object that accesses unmanaged resources, such as a , a good practice is to create the instance with a `using` statement. The `using` statement automatically closes the stream and calls on the object when the code that is using it has completed. For an example, see the class. - - - ## Examples The following example shows how you can implement the method. - [!code-cpp[System.IDisposable.Dispose Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CPP/idisposabledispose.cpp#1)] [!code-csharp[System.IDisposable.Dispose Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CS/idisposabledispose.cs#1)] [!code-vb[System.IDisposable.Dispose Example#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/VB/idisposabledispose.vb#1)] - - ]]> - + To be added. @@ -168,21 +134,7 @@ Use this method to close or release unmanaged resources such as files, streams, Advances the enumerator to the next element of the immutable dictionary. if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the dictionary. - - method is called, an enumerator is positioned before the first element of the collection, and the first call to the method moves the enumerator over the first element of the collection. - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false` until is called. - If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of is undefined. - - - ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. - [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] - - ]]> - + To be added. The dictionary was modified after the enumerator was created. @@ -214,20 +166,7 @@ After an enumerator is created or after the Sets the enumerator to its initial position, which is before the first element in the dictionary. - - is undefined. - The method is provided for COM interoperability. It does not necessarily need to be implemented; instead, the implementer can simply throw a . - - - ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. - [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] - - ]]> - + To be added. The dictionary was modified after the enumerator was created. @@ -265,18 +204,6 @@ If changes are made to the collection, such as adding, modifying, or deleting el ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - is undefined under any of the following conditions: - - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . - - The last call to returned `false`, which indicates the end of the collection. - - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - returns the same object until is called. sets to the next element. - - - ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. - [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] ]]> diff --git a/xml/System.Collections.Immutable/ImmutableDictionary`2.xml b/xml/System.Collections.Immutable/ImmutableDictionary`2.xml index 31dc5f587a1..aa3c88c7c6f 100644 --- a/xml/System.Collections.Immutable/ImmutableDictionary`2.xml +++ b/xml/System.Collections.Immutable/ImmutableDictionary`2.xml @@ -256,16 +256,7 @@ Determines whether the immutable dictionary contains an element with the specified key. if the immutable dictionary contains an element with the specified key; otherwise, . - - might use the property, or it might implement the method. - Implementations can vary in whether they allow `key` to be `null`. - - ]]> - + To be added. @@ -454,17 +445,7 @@ Implementations can vary in how they determine the equality of objects; for exam The type of the key. Gets the associated with the specified key. The value associated with the specified key. If no results are found, the operation throws an exception. - - might use the property, or it might implement the method. - Implementations can vary in whether they allow `key` to be `null`. - - ]]> - + To be added. @@ -531,15 +512,7 @@ This property lets you access a specific element in the collection by using the Gets the keys in the immutable dictionary. The keys in the immutable dictionary. - - property. - - ]]> - + To be added. @@ -741,15 +714,7 @@ The order of the keys in the enumerable collection is unspecified, but the imple Removes all items from the . - - must be set to 0, and references to other objects from elements of the collection must be released. - - ]]> - + To be added. @@ -817,15 +782,7 @@ The order of the keys in the enumerable collection is unspecified, but the imple Gets a value indicating whether the is read-only. if the is read-only; otherwise, . - - interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. - - ]]> - + To be added. @@ -861,16 +818,7 @@ A collection that is read-only does not allow the addition or removal of element Removes the first occurrence of a specific object from the . if was successfully removed from the ; otherwise, . This method also returns if is not found in the original . - - uses , whereas, allows the user to specify the implementation to use for comparing keys. - In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. - - ]]> - + To be added. @@ -906,22 +854,7 @@ Implementations can vary in how they determine equality of objects; for example, The object to use as the key of the element to add. The object to use as the value of the element to add. Adds an element with the provided key and value to the immutable dictionary. - - property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. - Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. - Implementations can vary in whether they allow `key` to be `null`. - - - ## Examples The following code example creates an empty of strings, with integer keys, and accesses it through the interface. The code example uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#2](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#2)] [!code-csharp[Generic.IDictionary#2](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#2)] [!code-vb[Generic.IDictionary#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#2)] - - ]]> - + To be added. @@ -956,25 +889,7 @@ You can also use the p The type of the key. Gets or sets the with the specified key. An object of type associated with the . - - property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. - Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. - The C# language uses the [this](~/docs/csharp/language-reference/keywords/this.md) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. - Implementations can vary in whether they allow `key` to be `null`. - - - ## Examples The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. - The example also shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#3](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#3)] [!code-csharp[Generic.IDictionary#3](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#3)] [!code-vb[Generic.IDictionary#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#3)] [!code-cpp[Generic.IDictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#4)] [!code-csharp[Generic.IDictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#4)] [!code-vb[Generic.IDictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#4)] [!code-cpp[Generic.IDictionary#5](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#5)] [!code-csharp[Generic.IDictionary#5](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#5)] [!code-vb[Generic.IDictionary#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#5)] - - ]]> - + To be added. @@ -1005,20 +920,7 @@ This property provides the ability to access a specific element in the collectio Gets the keys. A collection containing the keys. - - is unspecified, but it is guaranteed to be the same order as the corresponding values in the returned by the property. - - - ## Examples The following code example shows how to enumerate keys alone using the property. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#9](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#9)] [!code-csharp[Generic.IDictionary#9](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#9)] [!code-vb[Generic.IDictionary#9](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#9)] - - ]]> - + To be added. @@ -1054,20 +956,7 @@ The order of the keys in the returned Removes the element with the specified key from the generic dictionary. if the element is successfully removed; otherwise, . This method also returns if was not found in the original generic dictionary. - - class uses , whereas the class allows the user to specify the implementation to use for comparing keys. - - - ## Examples The following code example shows how to remove a key/value pair from a dictionary using the method. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#10](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#10)] [!code-csharp[Generic.IDictionary#10](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#10)] [!code-vb[Generic.IDictionary#10](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#10)] - - ]]> - + To be added. @@ -1098,20 +987,7 @@ Implementations can vary in how they determine equality of objects; for example, Gets the values. A collection containing the values. - - is unspecified, but it is guaranteed to be the same order as the corresponding keys in the returned by the property. - - - ## Examples The following code example shows how to enumerate values alone using the property. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#8](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#8)] [!code-csharp[Generic.IDictionary#8](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#8)] [!code-vb[Generic.IDictionary#8](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#8)] - - ]]> - + To be added. @@ -1143,25 +1019,7 @@ The order of the values in the returned Returns an enumerator that iterates through the collection. An enumerator that can be used to iterate through the collection. - - provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. - Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . - returns the same object until is called again as sets to the next element. - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. - An enumerator does not have exclusive access to the collection so an enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection. - Default implementations of collections in the namespace aren't synchronized. - - - ## Examples The following example demonstrates how to implement the interface and uses that implementation to create a LINQ query. When you implement , you must also implement or, for C# only, you can use the [yield](~/docs/csharp/language-reference/keywords/yield.md) keyword. Implementing also requires to be implemented, which you will see in this example. - [!code-csharp[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/cs/program.cs#1)] [!code-vb[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/vb/module1.vb#1)] - For another C# example that demonstrates how to implement the interface, see the [Generics Sample](https://code.msdn.microsoft.com/Generics-Sample-C-9b41a192/sourcecode?fileId=46476&pathId=1364935593). This sample uses of the `yield` keyword instead of implementing . - - ]]> - + To be added. @@ -1247,14 +1105,6 @@ The returned provides the abil ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - returns an object, which can be used to synchronize access to the . - Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] ]]> @@ -1293,25 +1143,7 @@ This member is an explicit interface member implementation. It can be used only Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . - - instance is cast to an interface. - - - - For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. - In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: - [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] - - ]]> - + To be added. @@ -1513,15 +1345,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but does allow the modification of existing elements. - A collection with a fixed size is simply a collection with a wrapper that prevents adding and removing elements; therefore, if changes are made to the underlying collection, including the addition or removal of elements, the fixed-size collection reflects those changes. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#6](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#6)] [!code-csharp[Dictionary#6](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#6)] [!code-vb[Dictionary#6](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#6)] ]]> @@ -1562,14 +1385,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#4)] [!code-csharp[Dictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#4)] [!code-vb[Dictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#4)] ]]> @@ -1607,22 +1422,7 @@ This member is an explicit interface member implementation. It can be used only The key. Gets or sets the element with the specified key. The value stored under the specified key. - - property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. - Implementations can vary in whether they allow the key to be `null`. - The C# language uses the `this`[this](~/docs/csharp/language-reference/keywords/this.md) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#13](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#13)] [!code-csharp[Dictionary#13](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#13)] [!code-vb[Dictionary#13](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#13)] - - ]]> - + To be added. @@ -1659,14 +1459,6 @@ This property provides the ability to access a specific element in the collectio ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - The order of the keys in the returned object is unspecified, but is guaranteed to be the same order as the corresponding values in the returned by the property. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#10](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#10)] [!code-csharp[Dictionary#10](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#10)] [!code-vb[Dictionary#10](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#10)] ]]> @@ -1747,14 +1539,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - The order of the values in the returned object is unspecified, but is guaranteed to be the same order as the corresponding keys in the returned by the property. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#11](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#11)] [!code-csharp[Dictionary#11](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#11)] [!code-vb[Dictionary#11](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#11)] ]]> @@ -1833,15 +1617,7 @@ This member is an explicit interface member implementation. It can be used only Value of the entry to be added. See the interface A new immutable dictionary that contains the additional key/value pair. - - - + To be added. @@ -2015,15 +1791,7 @@ If the given key/value pair already exists in the dictionary, this method return Value of the entry to be added. See the interface A new immutable dictionary that contains the specified key/value pair. - - - + To be added. @@ -2184,16 +1952,7 @@ If the specified key/value pair already exists in the dictionary, this method re Gets the value associated with the specified key. if the object that implements the dictionary contains an element with the specified key; otherwise, . - - method and the property. - If the key is not found, the `value` parameter gets the appropriate default value for the type `TValue`: for example, 0 (zero) for integer types, `false` for Boolean types, and `null` for reference types. - - ]]> - + To be added. is null. @@ -2262,15 +2021,7 @@ This method combines the functionality of the Gets the values in the immutable dictionary. The values in the immutable dictionary. - - property. - - ]]> - + To be added. diff --git a/xml/System.Collections.Immutable/ImmutableHashSet`1+Builder.xml b/xml/System.Collections.Immutable/ImmutableHashSet`1+Builder.xml index 66c1c8b72e4..4600c47fb6d 100644 --- a/xml/System.Collections.Immutable/ImmutableHashSet`1+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableHashSet`1+Builder.xml @@ -123,15 +123,7 @@ Removes all items from the immutable hash set. - - must be set to 0, and references to other objects from elements of the collection must be released. - - ]]> - + To be added. The hash set is read-only. @@ -168,15 +160,7 @@ Determines whether the immutable hash set contains a specific value. if is found in the hash set ; otherwise, . - - uses , whereas allows the user to specify the implementation to use for comparing keys. - - ]]> - + To be added. @@ -242,15 +226,7 @@ Implementations can vary in how they determine equality of objects; for example, The collection of items to remove from the set. Removes all elements in the specified collection from the current hash set. - - - + To be added. @@ -313,15 +289,7 @@ This method is an O(`n`) operation, where `n` is the number of elements in the ` The collection to compare to the current set. Modifies the current set so that it contains only elements that are also in a specified collection. - - - + To be added. @@ -357,17 +325,7 @@ This method ignores any duplicate elements in `other`. Determines whether the current set is a proper (strict) subset of a specified collection. if the current set is a proper subset of ; otherwise, . - - - + To be added. @@ -403,17 +361,7 @@ If the current set is a proper subset of `other`, `other` must have at least one Determines whether the current set is a proper (strict) superset of a specified collection. if the current set is a proper superset of ; otherwise, . - - - + To be added. @@ -449,16 +397,7 @@ If the current set is a proper superset of `other`, the current set must have at Determines whether the current set is a subset of a specified collection. if the current set is a subset of ; otherwise, . - - - + To be added. @@ -494,16 +433,7 @@ If `other` contains the same elements as the current set, the current set is sti Determines whether the current set is a superset of a specified collection. if the current set is a superset of ; otherwise, . - - - + To be added. @@ -567,15 +497,7 @@ If `other` contains the same elements as the current set, the current set is sti Determines whether the current set overlaps with the specified collection. if the current set and share at least one common element; otherwise, . - - - + To be added. @@ -611,16 +533,7 @@ Any duplicate elements in `other` are ignored. Removes the first occurrence of a specific object from the immutable hash set. if was successfully removed from the set ; otherwise, . This method also returns if is not found in the original set. - - uses , whereas, allows the user to specify the implementation to use for comparing keys. - In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. - - ]]> - + To be added. The set is read-only. @@ -657,15 +570,7 @@ Implementations can vary in how they determine equality of objects; for example, Determines whether the current set and the specified collection contain the same elements. if the current set is equal to ; otherwise, . - - - + To be added. @@ -699,15 +604,7 @@ This method ignores the order of elements and any duplicate elements in `other`. The collection to compare to the current set. Modifies the current set so that it contains only elements that are present either in the current set or in the specified collection, but not both. - - - + To be added. @@ -824,15 +721,7 @@ Any duplicate elements in `other` are ignored. Gets a value indicating whether the is read-only. if the is read-only; otherwise, . - - interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. - - ]]> - + To be added. @@ -980,15 +869,7 @@ A collection that is read-only does not allow the addition or removal of element The collection to compare to the current set. Modifies the current set so that it contains all elements that are present in both the current set and in the specified collection. - - - + To be added. diff --git a/xml/System.Collections.Immutable/ImmutableHashSet`1+Enumerator.xml b/xml/System.Collections.Immutable/ImmutableHashSet`1+Enumerator.xml index 454fd322cba..edf0fa570eb 100644 --- a/xml/System.Collections.Immutable/ImmutableHashSet`1+Enumerator.xml +++ b/xml/System.Collections.Immutable/ImmutableHashSet`1+Enumerator.xml @@ -69,19 +69,7 @@ Gets the element at the current position of the enumerator. The element at the current position of the enumerator. - - is undefined under any of the following conditions: - - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . - - The last call to returned `false`, which indicates the end of the collection. - - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - returns the same object until is called. sets to the next element. - - ]]> - + To be added. @@ -112,29 +100,7 @@ Releases the resources used by the current instance of the class. - - [!WARNING] > If you are using a class that implements the interface, you should call its implementation when you are finished using the class. For more information, see the "Using an object that implements IDisposable" section in the topic. - When implementing this method, ensure that all held resources are freed by propagating the call through the containment hierarchy. For example, if an object A allocates an object B, and object B allocates an object C, then A's implementation must call on B, which must in turn call on C. - > [!IMPORTANT] > The C++ compiler supports deterministic disposal of resources and does not allow direct implementation of the method. - An object must also call the method of its base class if the base class implements . For more information about implementing on a base class and its subclasses, see the "IDisposable and the inheritance hierarchy" section in the topic. - If an object's method is called more than once, the object must ignore all calls after the first one. The object must not throw an exception if its method is called multiple times. Instance methods other than can throw an when resources are already disposed. - Users might expect a resource type to use a particular convention to denote an allocated state versus a freed state. An example of this is stream classes, which are traditionally thought of as open or closed. The implementer of a class that has such a convention might choose to implement a public method with a customized name, such as `Close`, that calls the method. - Because the method must be called explicitly, there is always a danger that the unmanaged resources will not be released, because the consumer of an object fails to call its method. There are two ways to avoid this: - - Wrap the managed resource in an object derived from . Your implementation then calls the method of the instances. For more information, see "The SafeHandle alternative" section in the topic. - - Implement a finalizer to free resources when is not called. By default, the garbage collector automatically calls an object's finalizer before reclaiming its memory. However, if the method has been called, it is typically unnecessary for the garbage collector to call the disposed object's finalizer. To prevent automatic finalization, implementations can call the method. - When you use an object that accesses unmanaged resources, such as a , a good practice is to create the instance with a `using` statement. The `using` statement automatically closes the stream and calls on the object when the code that is using it has completed. For an example, see the class. - - - ## Examples The following example shows how you can implement the method. - [!code-cpp[System.IDisposable.Dispose Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CPP/idisposabledispose.cpp#1)] [!code-csharp[System.IDisposable.Dispose Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CS/idisposabledispose.cs#1)] [!code-vb[System.IDisposable.Dispose Example#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/VB/idisposabledispose.vb#1)] - - ]]> - + To be added. @@ -167,21 +133,7 @@ Use this method to close or release unmanaged resources such as files, streams, Advances the enumerator to the next element of the immutable hash set. if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the hash set. - - method is called, an enumerator is positioned before the first element of the collection, and the first call to the method moves the enumerator over the first element of the collection. - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false` until is called. - If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of is undefined. - - - ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. - [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] - - ]]> - + To be added. The hash set was modified after the enumerator was created. @@ -213,20 +165,7 @@ After an enumerator is created or after the Sets the enumerator to its initial position, which is before the first element in the hash set. - - is undefined. - The method is provided for COM interoperability. It does not necessarily need to be implemented; instead, the implementer can simply throw a . - - - ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. - [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] - - ]]> - + To be added. The hash set was modified after the enumerator was created. @@ -264,18 +203,6 @@ If changes are made to the collection, such as adding, modifying, or deleting el ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - is undefined under any of the following conditions: - - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . - - The last call to returned `false`, which indicates the end of the collection. - - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - returns the same object until is called. sets to the next element. - - - ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. - [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] ]]> diff --git a/xml/System.Collections.Immutable/ImmutableHashSet`1.xml b/xml/System.Collections.Immutable/ImmutableHashSet`1.xml index 20427e1c141..3194cc1e6db 100644 --- a/xml/System.Collections.Immutable/ImmutableHashSet`1.xml +++ b/xml/System.Collections.Immutable/ImmutableHashSet`1.xml @@ -826,15 +826,7 @@ See the interface. To be added. - - interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. - - ]]> - + To be added. @@ -1208,14 +1200,6 @@ A collection that is read-only does not allow the addition or removal of element ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - returns an object, which can be used to synchronize access to the . - Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] ]]> @@ -1260,16 +1244,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. - In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: - [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] ]]> diff --git a/xml/System.Collections.Immutable/ImmutableList`1+Builder.xml b/xml/System.Collections.Immutable/ImmutableList`1+Builder.xml index f5630548700..774bd73eaf6 100644 --- a/xml/System.Collections.Immutable/ImmutableList`1+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableList`1+Builder.xml @@ -312,15 +312,7 @@ Removes all items from the immutable list. - - must be set to 0, and references to other objects from elements of the collection must be released. - - ]]> - + To be added. @@ -356,15 +348,7 @@ Determines whether the immutable list contains a specific value. if item is found in the list; otherwise, . - - uses , whereas allows the user to specify the implementation to use for comparing keys. - - ]]> - + To be added. @@ -1044,15 +1028,7 @@ Implementations can vary in how they determine equality of objects; for example, The object to locate in the immutable list. The value can be for reference types. Searches for the specified object and returns the zero-based index of the first occurrence within the range of elements in the immutable list. The zero-based index of the first occurrence of within the range of elements in the immutable list, if found; otherwise, -1. - - method always returns the first instance found. - - ]]> - + To be added. @@ -1196,16 +1172,7 @@ If an object occurs multiple times in the list, the The zero-based index at which should be inserted. The object to insert into the immutable list. Inserts an item to the immutable list at the specified index. - - , then `item` is appended to the list. - In collections of contiguous elements, such as lists, the elements that follow the insertion point move down to accommodate the new element. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. - - ]]> - + To be added. @@ -1273,16 +1240,7 @@ If `index` equals the number of items in the The index of the item to get or set. Gets or sets the value for a given index in the list. The value at the specified index. - - property. Visual Basic implements as a [default property](~/docs/visual-basic/language-reference/modifiers/default.md), which provides the same indexing functionality. - - ]]> - + To be added. @@ -1491,16 +1449,7 @@ This property provides the ability to access a specific element in the collectio Removes the first occurrence of a specific object from the immutable list. if item was successfully removed from the list; otherwise, . This method also returns if item is not found in the list. - - uses , whereas, allows the user to specify the implementation to use for comparing keys. - In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. - - ]]> - + To be added. @@ -1567,15 +1516,7 @@ Implementations can vary in how they determine equality of objects; for example, The zero-based index of the item to remove from the list. Removes the item at the specified index of the immutable list. - - - + To be added. @@ -1794,15 +1735,7 @@ In collections of contiguous elements, such as lists, the elements that follow t Gets a value that indicates whether this instance is read-only. Always . - - interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. - - ]]> - + To be added. @@ -1928,14 +1861,6 @@ A collection that is read-only does not allow the addition or removal of element ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - returns an object, which can be used to synchronize access to the . - Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] ]]> @@ -1980,16 +1905,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. - In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: - [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] ]]> @@ -2282,14 +2197,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements. - - - ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] ]]> @@ -2330,14 +2237,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. - - - ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] ]]> @@ -2375,20 +2274,7 @@ This member is an explicit interface member implementation. It can be used only The index. Gets or sets the at the specified index. The object at the specified index. - - property. Visual Basic implements as a default property, which provides the same indexing functionality. - - - ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] - - ]]> - + To be added. diff --git a/xml/System.Collections.Immutable/ImmutableList`1+Enumerator.xml b/xml/System.Collections.Immutable/ImmutableList`1+Enumerator.xml index e254e4b9cb7..07e9fcbdb7b 100644 --- a/xml/System.Collections.Immutable/ImmutableList`1+Enumerator.xml +++ b/xml/System.Collections.Immutable/ImmutableList`1+Enumerator.xml @@ -84,19 +84,7 @@ Gets the element at the current position of the enumerator. The element at the current position of the enumerator. - - is undefined under any of the following conditions: - - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . - - The last call to returned `false`, which indicates the end of the collection. - - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - returns the same object until is called. sets to the next element. - - ]]> - + To be added. @@ -127,29 +115,7 @@ Releases the resources used by the current instance of the class. - - [!WARNING] > If you are using a class that implements the interface, you should call its implementation when you are finished using the class. For more information, see the "Using an object that implements IDisposable" section in the topic. - When implementing this method, ensure that all held resources are freed by propagating the call through the containment hierarchy. For example, if an object A allocates an object B, and object B allocates an object C, then A's implementation must call on B, which must in turn call on C. - > [!IMPORTANT] > The C++ compiler supports deterministic disposal of resources and does not allow direct implementation of the method. - An object must also call the method of its base class if the base class implements . For more information about implementing on a base class and its subclasses, see the "IDisposable and the inheritance hierarchy" section in the topic. - If an object's method is called more than once, the object must ignore all calls after the first one. The object must not throw an exception if its method is called multiple times. Instance methods other than can throw an when resources are already disposed. - Users might expect a resource type to use a particular convention to denote an allocated state versus a freed state. An example of this is stream classes, which are traditionally thought of as open or closed. The implementer of a class that has such a convention might choose to implement a public method with a customized name, such as `Close`, that calls the method. - Because the method must be called explicitly, there is always a danger that the unmanaged resources will not be released, because the consumer of an object fails to call its method. There are two ways to avoid this: - - Wrap the managed resource in an object derived from . Your implementation then calls the method of the instances. For more information, see "The SafeHandle alternative" section in the topic. - - Implement a finalizer to free resources when is not called. By default, the garbage collector automatically calls an object's finalizer before reclaiming its memory. However, if the method has been called, it is typically unnecessary for the garbage collector to call the disposed object's finalizer. To prevent automatic finalization, implementations can call the method. - When you use an object that accesses unmanaged resources, such as a , a good practice is to create the instance with a `using` statement. The `using` statement automatically closes the stream and calls on the object when the code that is using it has completed. For an example, see the class. - - - ## Examples The following example shows how you can implement the method. - [!code-cpp[System.IDisposable.Dispose Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CPP/idisposabledispose.cpp#1)] [!code-csharp[System.IDisposable.Dispose Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CS/idisposabledispose.cs#1)] [!code-vb[System.IDisposable.Dispose Example#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/VB/idisposabledispose.vb#1)] - - ]]> - + To be added. @@ -182,21 +148,7 @@ Use this method to close or release unmanaged resources such as files, streams, Advances enumeration to the next element of the immutable list. if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the list. - - method is called, an enumerator is positioned before the first element of the collection, and the first call to the method moves the enumerator over the first element of the collection. - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false` until is called. - If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of is undefined. - - - ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. - [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] - - ]]> - + To be added. @@ -227,20 +179,7 @@ After an enumerator is created or after the Sets the enumerator to its initial position, which is before the first element in the immutable list. - - is undefined. - The method is provided for COM interoperability. It does not necessarily need to be implemented; instead, the implementer can simply throw a . - - - ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. - [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] - - ]]> - + To be added. @@ -277,18 +216,6 @@ If changes are made to the collection, such as adding, modifying, or deleting el ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - is undefined under any of the following conditions: - - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . - - The last call to returned `false`, which indicates the end of the collection. - - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - returns the same object until is called. sets to the next element. - - - ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. - [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] ]]> diff --git a/xml/System.Collections.Immutable/ImmutableList`1.xml b/xml/System.Collections.Immutable/ImmutableList`1.xml index 23d67b8dcca..dd3f4c1ad54 100644 --- a/xml/System.Collections.Immutable/ImmutableList`1.xml +++ b/xml/System.Collections.Immutable/ImmutableList`1.xml @@ -322,15 +322,7 @@ Determines whether this immutable list contains the specified value. if the list contains the specified value; otherwise, . - - uses , whereas allows the user to specify the implementation to use for comparing keys. - - ]]> - + To be added. @@ -1049,15 +1041,7 @@ Implementations can vary in how they determine equality of objects; for example, The object to locate in the immutable list. The value can be for reference types. Searches for the specified object and returns the zero-based index of the first occurrence within the entire immutable list. The zero-based index of the first occurrence of within the entire immutable list, if found; otherwise, ?1. - - method always returns the first instance found. - - ]]> - + To be added. @@ -1955,15 +1939,7 @@ If an object occurs multiple times in the list, the Gets a value indicating whether the is read-only. if the is read-only; otherwise, . - - interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. - - ]]> - + To be added. @@ -2124,16 +2100,7 @@ A collection that is read-only does not allow the addition or removal of element The zero-based index of the item to access. Gets or sets the value at the specified index. Value stored in the specified index. - - property. Visual Basic implements as a [default property](~/docs/visual-basic/language-reference/modifiers/default.md), which provides the same indexing functionality. - - ]]> - + To be added. Thrown from getter when is negative or not less than . Always thrown from the setter. @@ -2262,14 +2229,6 @@ This property provides the ability to access a specific element in the collectio ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - returns an object, which can be used to synchronize access to the . - Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] ]]> @@ -2314,16 +2273,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. - In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: - [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] ]]> @@ -2616,14 +2565,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements. - - - ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] ]]> @@ -2664,14 +2605,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. - - - ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] ]]> @@ -2709,20 +2642,7 @@ This member is an explicit interface member implementation. It can be used only The index. Gets or sets the at the specified index. The value at the specified index. - - property. Visual Basic implements as a default property, which provides the same indexing functionality. - - - ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] - - ]]> - + To be added. Thrown from getter when is negative or not less than . Always thrown from the setter. diff --git a/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Builder.xml b/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Builder.xml index d95a39d33cf..fc4c2ca0c2e 100644 --- a/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Builder.xml @@ -142,22 +142,7 @@ The key of the element to add. The value of the element to add. Adds an element that has the specified key and value to the immutable sorted dictionary. - - property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. - Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. - Implementations can vary in whether they allow `key` to be `null`. - - - ## Examples The following code example creates an empty of strings, with integer keys, and accesses it through the interface. The code example uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#2](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#2)] [!code-csharp[Generic.IDictionary#2](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#2)] [!code-vb[Generic.IDictionary#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#2)] - - ]]> - + To be added. @@ -220,15 +205,7 @@ You can also use the p Removes all items from the immutable sorted dictionary. - - must be set to 0, and references to other objects from elements of the collection must be released. - - ]]> - + To be added. @@ -264,15 +241,7 @@ You can also use the p Determines whether the immutable sorted dictionary contains a specific value. if is found in the dictionary; otherwise, . - - uses , whereas allows the user to specify the implementation to use for comparing keys. - - ]]> - + To be added. @@ -309,21 +278,7 @@ Implementations can vary in how they determine equality of objects; for example, Determines whether the immutable sorted dictionary contains an element with the specified key. if the dictionary contains an element with the key; otherwise, . - - class uses , whereas the class allows the user to specify the implementation to use for comparing keys. - Implementations can vary in whether they allow `key` to be `null`. - - - ## Examples The following code example shows how to use the method to test whether a key exists prior to calling the method. It also shows how to use the method, which can be a more efficient way to retrieve values if a program frequently tries key values that are not in the dictionary. Finally, it shows how to insert items using property (the indexer in C#). - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#6](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#6)] [!code-csharp[Generic.IDictionary#6](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#6)] [!code-vb[Generic.IDictionary#6](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#6)] [!code-cpp[Generic.IDictionary#5](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#5)] [!code-csharp[Generic.IDictionary#5](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#5)] [!code-vb[Generic.IDictionary#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#5)] [!code-cpp[Generic.IDictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#4)] [!code-csharp[Generic.IDictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#4)] [!code-vb[Generic.IDictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#4)] - - ]]> - + To be added. @@ -519,25 +474,7 @@ Implementations can vary in how they determine equality of objects; for example, The key to retrieve the value for. Gets or sets the value for a specified key in the immutable sorted dictionary. The value associated with the given key. - - property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. - Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. - The C# language uses the [this](~/docs/csharp/language-reference/keywords/this.md) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. - Implementations can vary in whether they allow `key` to be `null`. - - - ## Examples The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. - The example also shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#3](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#3)] [!code-csharp[Generic.IDictionary#3](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#3)] [!code-vb[Generic.IDictionary#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#3)] [!code-cpp[Generic.IDictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#4)] [!code-csharp[Generic.IDictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#4)] [!code-vb[Generic.IDictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#4)] [!code-cpp[Generic.IDictionary#5](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#5)] [!code-csharp[Generic.IDictionary#5](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#5)] [!code-vb[Generic.IDictionary#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#5)] - - ]]> - + To be added. @@ -596,15 +533,7 @@ This property provides the ability to access a specific element in the collectio Gets a strongly typed, read-only collection of elements. A strongly typed, read-only collection of elements. - - property. - - ]]> - + To be added. @@ -640,16 +569,7 @@ The order of the keys in the enumerable collection is unspecified, but the imple Removes the first occurrence of a specific object from the immutable sorted dictionary. if was successfully removed from the dictionary; otherwise, . This method also returns if is not found in the dictionary. - - uses , whereas, allows the user to specify the implementation to use for comparing keys. - In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. - - ]]> - + To be added. @@ -685,20 +605,7 @@ Implementations can vary in how they determine equality of objects; for example, Removes the element with the specified key from the immutable sorted dictionary. if the element is successfully removed; otherwise, . This method also returns if was not found in the original dictionary. - - class uses , whereas the class allows the user to specify the implementation to use for comparing keys. - - - ## Examples The following code example shows how to remove a key/value pair from a dictionary using the method. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#10](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#10)] [!code-csharp[Generic.IDictionary#10](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#10)] [!code-vb[Generic.IDictionary#10](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#10)] - - ]]> - + To be added. @@ -796,15 +703,7 @@ Implementations can vary in how they determine equality of objects; for example, Gets a value that indicates whether this instance is read-only. Always . - - interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. - - ]]> - + To be added. @@ -835,20 +734,7 @@ A collection that is read-only does not allow the addition or removal of element Returns a collection containing all keys stored in the dictionary. See A collection containing all keys stored in the dictionary. - - is unspecified, but it is guaranteed to be the same order as the corresponding values in the returned by the property. - - - ## Examples The following code example shows how to enumerate keys alone using the property. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#9](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#9)] [!code-csharp[Generic.IDictionary#9](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#9)] [!code-vb[Generic.IDictionary#9](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#9)] - - ]]> - + To be added. @@ -879,20 +765,7 @@ The order of the keys in the returned Returns a collection containing all values stored in the dictionary. See A collection containing all values stored in the dictionary. - - is unspecified, but it is guaranteed to be the same order as the corresponding keys in the returned by the property. - - - ## Examples The following code example shows how to enumerate values alone using the property. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#8](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#8)] [!code-csharp[Generic.IDictionary#8](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#8)] [!code-vb[Generic.IDictionary#8](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#8)] - - ]]> - + To be added. @@ -924,25 +797,7 @@ The order of the values in the returned See An enumerator that can be used to iterate through the collection. - - provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. - Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . - returns the same object until is called again as sets to the next element. - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. - An enumerator does not have exclusive access to the collection so an enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection. - Default implementations of collections in the namespace aren't synchronized. - - - ## Examples The following example demonstrates how to implement the interface and uses that implementation to create a LINQ query. When you implement , you must also implement or, for C# only, you can use the [yield](~/docs/csharp/language-reference/keywords/yield.md) keyword. Implementing also requires to be implemented, which you will see in this example. - [!code-csharp[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/cs/program.cs#1)] [!code-vb[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/vb/module1.vb#1)] - For another C# example that demonstrates how to implement the interface, see the [Generics Sample](https://code.msdn.microsoft.com/Generics-Sample-C-9b41a192/sourcecode?fileId=46476&pathId=1364935593). This sample uses of the `yield` keyword instead of implementing . - - ]]> - + To be added. @@ -1030,14 +885,6 @@ The returned provides the abil ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - returns an object, which can be used to synchronize access to the . - Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] ]]> @@ -1082,16 +929,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. - In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: - [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] ]]> @@ -1257,15 +1094,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but does allow the modification of existing elements. - A collection with a fixed size is simply a collection with a wrapper that prevents adding and removing elements; therefore, if changes are made to the underlying collection, including the addition or removal of elements, the fixed-size collection reflects those changes. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#6](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#6)] [!code-csharp[Dictionary#6](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#6)] [!code-vb[Dictionary#6](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#6)] ]]> @@ -1306,14 +1134,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#4)] [!code-csharp[Dictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#4)] [!code-vb[Dictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#4)] ]]> @@ -1351,22 +1171,7 @@ This member is an explicit interface member implementation. It can be used only The key. Gets or sets the element with the specified key. The value associated with the specified key. - - property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. - Implementations can vary in whether they allow the key to be `null`. - The C# language uses the `this`[this](~/docs/csharp/language-reference/keywords/this.md) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#13](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#13)] [!code-csharp[Dictionary#13](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#13)] [!code-vb[Dictionary#13](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#13)] - - ]]> - + To be added. @@ -1403,14 +1208,6 @@ This property provides the ability to access a specific element in the collectio ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - The order of the keys in the returned object is unspecified, but is guaranteed to be the same order as the corresponding values in the returned by the property. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#10](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#10)] [!code-csharp[Dictionary#10](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#10)] [!code-vb[Dictionary#10](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#10)] ]]> @@ -1491,14 +1288,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - The order of the values in the returned object is unspecified, but is guaranteed to be the same order as the corresponding keys in the returned by the property. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#11](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#11)] [!code-csharp[Dictionary#11](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#11)] [!code-vb[Dictionary#11](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#11)] ]]> @@ -1663,21 +1452,7 @@ This member is an explicit interface member implementation. It can be used only Gets the value associated with the specified key. if the object that implements the dictionary contains an element with the specified key; otherwise, . - - method and the property. - If the key is not found, then the `value` parameter gets the appropriate default value for the type `TValue`; for example, zero (0) for integer types, `false` for Boolean types, and `null` for reference types. - - - ## Examples The example shows how to use the method to retrieve values. If a program frequently tries key values that are not in a dictionary, the method can be more efficient than using the property (the indexer in C#), which throws exceptions when attempting to retrieve nonexistent keys. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#5](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#5)] [!code-csharp[Generic.IDictionary#5](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#5)] [!code-vb[Generic.IDictionary#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#5)] [!code-cpp[Generic.IDictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#4)] [!code-csharp[Generic.IDictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#4)] [!code-vb[Generic.IDictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#4)] - - ]]> - + To be added. @@ -1770,15 +1545,7 @@ This method combines the functionality of the Gets a collection that contains the values of the immutable sorted dictionary. A collection that contains the values of the object that implements the dictionary. - - property. - - ]]> - + To be added. diff --git a/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Enumerator.xml b/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Enumerator.xml index aca838f6e43..3cb47280a05 100644 --- a/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Enumerator.xml +++ b/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Enumerator.xml @@ -85,19 +85,7 @@ Gets the element at the current position of the enumerator. The element at the current position of the enumerator. - - is undefined under any of the following conditions: - - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . - - The last call to returned `false`, which indicates the end of the collection. - - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - returns the same object until is called. sets to the next element. - - ]]> - + To be added. @@ -128,29 +116,7 @@ Releases the resources used by the current instance of the class. - - [!WARNING] > If you are using a class that implements the interface, you should call its implementation when you are finished using the class. For more information, see the "Using an object that implements IDisposable" section in the topic. - When implementing this method, ensure that all held resources are freed by propagating the call through the containment hierarchy. For example, if an object A allocates an object B, and object B allocates an object C, then A's implementation must call on B, which must in turn call on C. - > [!IMPORTANT] > The C++ compiler supports deterministic disposal of resources and does not allow direct implementation of the method. - An object must also call the method of its base class if the base class implements . For more information about implementing on a base class and its subclasses, see the "IDisposable and the inheritance hierarchy" section in the topic. - If an object's method is called more than once, the object must ignore all calls after the first one. The object must not throw an exception if its method is called multiple times. Instance methods other than can throw an when resources are already disposed. - Users might expect a resource type to use a particular convention to denote an allocated state versus a freed state. An example of this is stream classes, which are traditionally thought of as open or closed. The implementer of a class that has such a convention might choose to implement a public method with a customized name, such as `Close`, that calls the method. - Because the method must be called explicitly, there is always a danger that the unmanaged resources will not be released, because the consumer of an object fails to call its method. There are two ways to avoid this: - - Wrap the managed resource in an object derived from . Your implementation then calls the method of the instances. For more information, see "The SafeHandle alternative" section in the topic. - - Implement a finalizer to free resources when is not called. By default, the garbage collector automatically calls an object's finalizer before reclaiming its memory. However, if the method has been called, it is typically unnecessary for the garbage collector to call the disposed object's finalizer. To prevent automatic finalization, implementations can call the method. - When you use an object that accesses unmanaged resources, such as a , a good practice is to create the instance with a `using` statement. The `using` statement automatically closes the stream and calls on the object when the code that is using it has completed. For an example, see the class. - - - ## Examples The following example shows how you can implement the method. - [!code-cpp[System.IDisposable.Dispose Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CPP/idisposabledispose.cpp#1)] [!code-csharp[System.IDisposable.Dispose Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CS/idisposabledispose.cs#1)] [!code-vb[System.IDisposable.Dispose Example#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/VB/idisposabledispose.vb#1)] - - ]]> - + To be added. @@ -183,21 +149,7 @@ Use this method to close or release unmanaged resources such as files, streams, Advances the enumerator to the next element of the immutable sorted dictionary. if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the sorted dictionary. - - method is called, an enumerator is positioned before the first element of the collection, and the first call to the method moves the enumerator over the first element of the collection. - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false` until is called. - If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of is undefined. - - - ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. - [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] - - ]]> - + To be added. @@ -228,20 +180,7 @@ After an enumerator is created or after the Sets the enumerator to its initial position, which is before the first element in the immutable sorted dictionary. - - is undefined. - The method is provided for COM interoperability. It does not necessarily need to be implemented; instead, the implementer can simply throw a . - - - ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. - [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] - - ]]> - + To be added. @@ -278,18 +217,6 @@ If changes are made to the collection, such as adding, modifying, or deleting el ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - is undefined under any of the following conditions: - - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . - - The last call to returned `false`, which indicates the end of the collection. - - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - returns the same object until is called. sets to the next element. - - - ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. - [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] ]]> diff --git a/xml/System.Collections.Immutable/ImmutableSortedDictionary`2.xml b/xml/System.Collections.Immutable/ImmutableSortedDictionary`2.xml index 16a63acaeca..442f0d0061a 100644 --- a/xml/System.Collections.Immutable/ImmutableSortedDictionary`2.xml +++ b/xml/System.Collections.Immutable/ImmutableSortedDictionary`2.xml @@ -249,16 +249,7 @@ Determines whether this immutable sorted map contains the specified key. if the immutable dictionary contains the specified key; otherwise, . - - might use the property, or it might implement the method. - Implementations can vary in whether they allow `key` to be `null`. - - ]]> - + To be added. @@ -444,17 +435,7 @@ Implementations can vary in how they determine the equality of objects; for exam The key to retrieve the value for. Gets the associated with the specified key. The value associated with the specified key. If no results are found, the operation throws an exception. - - might use the property, or it might implement the method. - Implementations can vary in whether they allow `key` to be `null`. - - ]]> - + To be added. @@ -513,15 +494,7 @@ This property lets you access a specific element in the collection by using the Gets the keys in the immutable sorted dictionary. The keys in the immutable dictionary. - - property. - - ]]> - + To be added. @@ -723,15 +696,7 @@ The order of the keys in the enumerable collection is unspecified, but the imple Removes all items from the . - - must be set to 0, and references to other objects from elements of the collection must be released. - - ]]> - + To be added. @@ -799,15 +764,7 @@ The order of the keys in the enumerable collection is unspecified, but the imple Gets a value indicating whether the is read-only. if the is read-only; otherwise, . - - interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. - - ]]> - + To be added. @@ -843,16 +800,7 @@ A collection that is read-only does not allow the addition or removal of element Removes the first occurrence of a specific object from the . if was successfully removed from the ; otherwise, . This method also returns if is not found in the original . - - uses , whereas, allows the user to specify the implementation to use for comparing keys. - In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. - - ]]> - + To be added. @@ -888,22 +836,7 @@ Implementations can vary in how they determine equality of objects; for example, The object to use as the key of the element to add. The object to use as the value of the element to add. Adds an element with the provided key and value to the generic dictionary. - - property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. - Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. - Implementations can vary in whether they allow `key` to be `null`. - - - ## Examples The following code example creates an empty of strings, with integer keys, and accesses it through the interface. The code example uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#2](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#2)] [!code-csharp[Generic.IDictionary#2](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#2)] [!code-vb[Generic.IDictionary#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#2)] - - ]]> - + To be added. @@ -938,25 +871,7 @@ You can also use the p The object to use as the key of the element to access. Gets or sets the with the specified key. An object of type associated with the . - - property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. - Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. - The C# language uses the [this](~/docs/csharp/language-reference/keywords/this.md) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. - Implementations can vary in whether they allow `key` to be `null`. - - - ## Examples The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. - The example also shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#3](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#3)] [!code-csharp[Generic.IDictionary#3](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#3)] [!code-vb[Generic.IDictionary#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#3)] [!code-cpp[Generic.IDictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#4)] [!code-csharp[Generic.IDictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#4)] [!code-vb[Generic.IDictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#4)] [!code-cpp[Generic.IDictionary#5](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#5)] [!code-csharp[Generic.IDictionary#5](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#5)] [!code-vb[Generic.IDictionary#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#5)] - - ]]> - + To be added. @@ -987,20 +902,7 @@ This property provides the ability to access a specific element in the collectio Gets the keys. A collection containing the keys. - - is unspecified, but it is guaranteed to be the same order as the corresponding values in the returned by the property. - - - ## Examples The following code example shows how to enumerate keys alone using the property. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#9](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#9)] [!code-csharp[Generic.IDictionary#9](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#9)] [!code-vb[Generic.IDictionary#9](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#9)] - - ]]> - + To be added. @@ -1036,20 +938,7 @@ The order of the keys in the returned Removes the element with the specified key from the generic dictionary. if the element is successfully removed; otherwise, . This method also returns if was not found in the original generic dictionary. - - class uses , whereas the class allows the user to specify the implementation to use for comparing keys. - - - ## Examples The following code example shows how to remove a key/value pair from a dictionary using the method. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#10](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#10)] [!code-csharp[Generic.IDictionary#10](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#10)] [!code-vb[Generic.IDictionary#10](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#10)] - - ]]> - + To be added. @@ -1080,20 +969,7 @@ Implementations can vary in how they determine equality of objects; for example, Gets the values. A collection containing the values. - - is unspecified, but it is guaranteed to be the same order as the corresponding keys in the returned by the property. - - - ## Examples The following code example shows how to enumerate values alone using the property. - This code is part of a larger example that can be compiled and executed. See . - [!code-cpp[Generic.IDictionary#8](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#8)] [!code-csharp[Generic.IDictionary#8](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#8)] [!code-vb[Generic.IDictionary#8](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source.vb#8)] - - ]]> - + To be added. @@ -1125,25 +1001,7 @@ The order of the values in the returned Returns an enumerator that iterates through the collection. An enumerator that can be used to iterate through the collection. - - provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. - Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . - returns the same object until is called again as sets to the next element. - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. - An enumerator does not have exclusive access to the collection so an enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection. - Default implementations of collections in the namespace aren't synchronized. - - - ## Examples The following example demonstrates how to implement the interface and uses that implementation to create a LINQ query. When you implement , you must also implement or, for C# only, you can use the [yield](~/docs/csharp/language-reference/keywords/yield.md) keyword. Implementing also requires to be implemented, which you will see in this example. - [!code-csharp[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/cs/program.cs#1)] [!code-vb[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/vb/module1.vb#1)] - For another C# example that demonstrates how to implement the interface, see the [Generics Sample](https://code.msdn.microsoft.com/Generics-Sample-C-9b41a192/sourcecode?fileId=46476&pathId=1364935593). This sample uses of the `yield` keyword instead of implementing . - - ]]> - + To be added. @@ -1229,14 +1087,6 @@ The returned provides the abil ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - returns an object, which can be used to synchronize access to the . - Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] ]]> @@ -1281,16 +1131,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. - In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: - [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] ]]> @@ -1495,15 +1335,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but does allow the modification of existing elements. - A collection with a fixed size is simply a collection with a wrapper that prevents adding and removing elements; therefore, if changes are made to the underlying collection, including the addition or removal of elements, the fixed-size collection reflects those changes. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#6](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#6)] [!code-csharp[Dictionary#6](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#6)] [!code-vb[Dictionary#6](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#6)] ]]> @@ -1538,23 +1369,7 @@ This member is an explicit interface member implementation. It can be used only Gets a value indicating whether the is read-only. if the is read-only; otherwise, . - - instance is cast to an interface. - - - - A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#4](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#4)] [!code-csharp[Dictionary#4](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#4)] [!code-vb[Dictionary#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#4)] - - ]]> - + To be added. @@ -1589,22 +1404,7 @@ This member is an explicit interface member implementation. It can be used only The key of the element to be accessed. Gets or sets the element with the specified key. Value stored under the specified key. - - property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. - Implementations can vary in whether they allow the key to be `null`. - The C# language uses the `this`[this](~/docs/csharp/language-reference/keywords/this.md) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#13](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#13)] [!code-csharp[Dictionary#13](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#13)] [!code-vb[Dictionary#13](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#13)] - - ]]> - + To be added. @@ -1641,14 +1441,6 @@ This property provides the ability to access a specific element in the collectio ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - The order of the keys in the returned object is unspecified, but is guaranteed to be the same order as the corresponding values in the returned by the property. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#10](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#10)] [!code-csharp[Dictionary#10](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#10)] [!code-vb[Dictionary#10](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#10)] ]]> @@ -1729,14 +1521,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - The order of the values in the returned object is unspecified, but is guaranteed to be the same order as the corresponding keys in the returned by the property. - - - ## Examples The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. - [!code-cpp[Dictionary#11](~/samples/snippets/cpp/VS_Snippets_CLR/Dictionary/cpp/Dictionary.cpp#11)] [!code-csharp[Dictionary#11](~/samples/snippets/csharp/VS_Snippets_CLR/Dictionary/CS/Dictionary.cs#11)] [!code-vb[Dictionary#11](~/samples/snippets/visualbasic/VS_Snippets_CLR/Dictionary/VB/Dictionary.vb#11)] ]]> @@ -1815,15 +1599,7 @@ This member is an explicit interface member implementation. It can be used only Value of the entry to be added. See the interface. The instance. - - - + To be added. @@ -1997,15 +1773,7 @@ If the given key/value pair already exists in the dictionary, this method return Value of entry to be updated. See the interface. The instance. - - - + To be added. @@ -2166,16 +1934,7 @@ If the specified key/value pair already exists in the dictionary, this method re Gets the value associated with the specified key. if the dictionary contains an element with the specified key; otherwise, . - - method and the property. - If the key is not found, the `value` parameter gets the appropriate default value for the type `TValue`: for example, 0 (zero) for integer types, `false` for Boolean types, and `null` for reference types. - - ]]> - + To be added. @@ -2268,15 +2027,7 @@ This method combines the functionality of the Gets the values in the immutable sorted dictionary. The values in the dictionary. - - property. - - ]]> - + To be added. diff --git a/xml/System.Collections.Immutable/ImmutableSortedSet`1+Builder.xml b/xml/System.Collections.Immutable/ImmutableSortedSet`1+Builder.xml index b19a3ea7c93..232647133b3 100644 --- a/xml/System.Collections.Immutable/ImmutableSortedSet`1+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableSortedSet`1+Builder.xml @@ -129,15 +129,7 @@ Removes all elements from this set. - - must be set to 0, and references to other objects from elements of the collection must be released. - - ]]> - + To be added. @@ -173,15 +165,7 @@ Determines whether the set contains the specified object. if is found in the set; otherwise, . - - uses , whereas allows the user to specify the implementation to use for comparing keys. - - ]]> - + To be added. @@ -248,15 +232,7 @@ Implementations can vary in how they determine equality of objects; for example, The collection of items to remove from the set. Removes the specified set of items from the current set. - - - + To be added. @@ -319,15 +295,7 @@ This method is an O(`n`) operation, where `n` is the number of elements in the ` The collection to compare to the current set. Modifies the current set so that it contains only elements that are also in a specified collection. - - - + To be added. @@ -363,17 +331,7 @@ This method ignores any duplicate elements in `other`. Determines whether the current set is a proper (strict) subset of a specified collection. if the current set is a proper subset of ; otherwise, . - - - + To be added. @@ -409,17 +367,7 @@ If the current set is a proper subset of `other`, `other` must have at least one Determines whether the current set is a proper (strict) superset of a specified collection. if the current set is a proper superset of ; otherwise, . - - - + To be added. @@ -455,16 +403,7 @@ If the current set is a proper superset of `other`, the current set must have at Determines whether the current set is a subset of a specified collection. if the current set is a subset of ; otherwise, . - - - + To be added. @@ -500,16 +439,7 @@ If `other` contains the same elements as the current set, the current set is sti Determines whether the current set is a superset of a specified collection. if the current set is a superset of ; otherwise, . - - - + To be added. @@ -708,15 +638,7 @@ If `other` contains the same elements as the current set, the current set is sti Determines whether the current set overlaps with the specified collection. if the current set and share at least one common element; otherwise, . - - - + To be added. @@ -752,16 +674,7 @@ Any duplicate elements in `other` are ignored. Removes the first occurrence of the specified object from the set. if was removed from the set; if was not found in the set. - - uses , whereas, allows the user to specify the implementation to use for comparing keys. - In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. - - ]]> - + To be added. @@ -826,15 +739,7 @@ Implementations can vary in how they determine equality of objects; for example, Determines whether the current set and the specified collection contain the same elements. if the current set is equal to ; otherwise, . - - - + To be added. @@ -868,15 +773,7 @@ This method ignores the order of elements and any duplicate elements in `other`. The collection to compare to the current set. Modifies the current set so that it contains only elements that are present either in the current set or in the specified collection, but not both. - - - + To be added. @@ -991,15 +888,7 @@ Any duplicate elements in `other` are ignored. Gets a value that indicates whether this instance is read-only. Always . - - interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. - - ]]> - + To be added. @@ -1124,14 +1013,6 @@ A collection that is read-only does not allow the addition or removal of element ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - returns an object, which can be used to synchronize access to the . - Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] ]]> @@ -1176,16 +1057,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. - In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: - [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] ]]> @@ -1297,15 +1168,7 @@ This member is an explicit interface member implementation. It can be used only The collection to compare to the current state. Modifies the current set so that it contains all elements that are present in both the current set and in the specified collection. - - - + To be added. diff --git a/xml/System.Collections.Immutable/ImmutableSortedSet`1+Enumerator.xml b/xml/System.Collections.Immutable/ImmutableSortedSet`1+Enumerator.xml index 828accb1354..273e92d43fb 100644 --- a/xml/System.Collections.Immutable/ImmutableSortedSet`1+Enumerator.xml +++ b/xml/System.Collections.Immutable/ImmutableSortedSet`1+Enumerator.xml @@ -86,19 +86,7 @@ **NuGet package**: System.Collections.Immutable (about immutable collections and how to install) The element at the current position of the enumerator. - - is undefined under any of the following conditions: - - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . - - The last call to returned `false`, which indicates the end of the collection. - - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - returns the same object until is called. sets to the next element. - - ]]> - + To be added. @@ -131,29 +119,7 @@ Releases the resources used by the current instance of the class. **NuGet package**: System.Collections.Immutable (about immutable collections and how to install) - - [!WARNING] > If you are using a class that implements the interface, you should call its implementation when you are finished using the class. For more information, see the "Using an object that implements IDisposable" section in the topic. - When implementing this method, ensure that all held resources are freed by propagating the call through the containment hierarchy. For example, if an object A allocates an object B, and object B allocates an object C, then A's implementation must call on B, which must in turn call on C. - > [!IMPORTANT] > The C++ compiler supports deterministic disposal of resources and does not allow direct implementation of the method. - An object must also call the method of its base class if the base class implements . For more information about implementing on a base class and its subclasses, see the "IDisposable and the inheritance hierarchy" section in the topic. - If an object's method is called more than once, the object must ignore all calls after the first one. The object must not throw an exception if its method is called multiple times. Instance methods other than can throw an when resources are already disposed. - Users might expect a resource type to use a particular convention to denote an allocated state versus a freed state. An example of this is stream classes, which are traditionally thought of as open or closed. The implementer of a class that has such a convention might choose to implement a public method with a customized name, such as `Close`, that calls the method. - Because the method must be called explicitly, there is always a danger that the unmanaged resources will not be released, because the consumer of an object fails to call its method. There are two ways to avoid this: - - Wrap the managed resource in an object derived from . Your implementation then calls the method of the instances. For more information, see "The SafeHandle alternative" section in the topic. - - Implement a finalizer to free resources when is not called. By default, the garbage collector automatically calls an object's finalizer before reclaiming its memory. However, if the method has been called, it is typically unnecessary for the garbage collector to call the disposed object's finalizer. To prevent automatic finalization, implementations can call the method. - When you use an object that accesses unmanaged resources, such as a , a good practice is to create the instance with a `using` statement. The `using` statement automatically closes the stream and calls on the object when the code that is using it has completed. For an example, see the class. - - - ## Examples The following example shows how you can implement the method. - [!code-cpp[System.IDisposable.Dispose Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CPP/idisposabledispose.cpp#1)] [!code-csharp[System.IDisposable.Dispose Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CS/idisposabledispose.cs#1)] [!code-vb[System.IDisposable.Dispose Example#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/VB/idisposabledispose.vb#1)] - - ]]> - + To be added. @@ -188,21 +154,7 @@ Use this method to close or release unmanaged resources such as files, streams, **NuGet package**: System.Collections.Immutable (about immutable collections and how to install) if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the sorted set. - - method is called, an enumerator is positioned before the first element of the collection, and the first call to the method moves the enumerator over the first element of the collection. - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false` until is called. - If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of is undefined. - - - ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. - [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] - - ]]> - + To be added. @@ -235,20 +187,7 @@ After an enumerator is created or after the Sets the enumerator to its initial position, which is before the first element in the immutable sorted set. **NuGet package**: System.Collections.Immutable (about immutable collections and how to install) - - is undefined. - The method is provided for COM interoperability. It does not necessarily need to be implemented; instead, the implementer can simply throw a . - - - ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. - [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] - - ]]> - + To be added. @@ -285,18 +224,6 @@ If changes are made to the collection, such as adding, modifying, or deleting el ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - is undefined under any of the following conditions: - - The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . - - The last call to returned `false`, which indicates the end of the collection. - - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - returns the same object until is called. sets to the next element. - - - ## Examples The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`for each` in Visual Basic). This code example is part of a larger example for the interface. - [!code-csharp[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/cs/ienumerator.cs#2)] [!code-vb[System.Collections_EnumeratorInterfaces#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb#2)] ]]> diff --git a/xml/System.Collections.Immutable/ImmutableSortedSet`1.xml b/xml/System.Collections.Immutable/ImmutableSortedSet`1.xml index 4629e8ea115..1bce16d18e0 100644 --- a/xml/System.Collections.Immutable/ImmutableSortedSet`1.xml +++ b/xml/System.Collections.Immutable/ImmutableSortedSet`1.xml @@ -1263,15 +1263,7 @@ This member is an explicit interface member implementation. It can be used only Returns true, since immutable collections are always read-only. See the interface. A boolean value indicating whether the collection is read-only. - - interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. - - ]]> - + To be added. @@ -1446,16 +1438,7 @@ This member is an explicit interface member implementation. It can be used only The zero-based index of the item to access. See the interface. The element stored at the specified index. - - property. Visual Basic implements as a [default property](~/docs/visual-basic/language-reference/modifiers/default.md), which provides the same indexing functionality. - - ]]> - + To be added. @@ -1823,14 +1806,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - returns an object, which can be used to synchronize access to the . - Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] ]]> @@ -1875,16 +1850,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. - In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: - [!code-cpp[System.Collections.ICollection#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#2)] [!code-csharp[System.Collections.ICollection#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#2)] [!code-vb[System.Collections.ICollection#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#2)] - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - [!code-cpp[System.Collections.ICollection#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp#1)] [!code-csharp[System.Collections.ICollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.icollection/cs/remarks.cs#1)] [!code-vb[System.Collections.ICollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb#1)] ]]> @@ -2205,14 +2170,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements. - - - ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] ]]> @@ -2253,14 +2210,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. - - - ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] ]]> @@ -2298,20 +2247,7 @@ This member is an explicit interface member implementation. It can be used only The index. Gets or sets the at the specified index. The . - - property. Visual Basic implements as a default property, which provides the same indexing functionality. - - - ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] - - ]]> - + To be added. From a2f81d66eda818edc97753b2740c8d9cb20e36da Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 1 Apr 2020 22:08:43 +0100 Subject: [PATCH 17/17] address more missing remarks --- .../ImmutableArray`1+Builder.xml | 31 ++----------------- .../ImmutableArray`1.xml | 25 ++------------- 2 files changed, 5 insertions(+), 51 deletions(-) diff --git a/xml/System.Collections.Immutable/ImmutableArray`1+Builder.xml b/xml/System.Collections.Immutable/ImmutableArray`1+Builder.xml index 76f59161163..71ddfc0270e 100644 --- a/xml/System.Collections.Immutable/ImmutableArray`1+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableArray`1+Builder.xml @@ -1067,16 +1067,7 @@ Removes the specified element. if was found and removed; otherwise, . - - uses , whereas, allows the user to specify the implementation to use for comparing keys. - In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. - - ]]> - + To be added. @@ -1110,15 +1101,7 @@ Implementations can vary in how they determine equality of objects; for example, The zero-based index of the item to remove. Removes the item at the specified index from the array. - - - + To be added. @@ -1304,15 +1287,7 @@ In collections of contiguous elements, such as lists, the elements that follow t Gets a value that indicates whether the is read-only. if the is read-only; otherwise, . - - interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. - - ]]> - + To be added. diff --git a/xml/System.Collections.Immutable/ImmutableArray`1.xml b/xml/System.Collections.Immutable/ImmutableArray`1.xml index a66c47414eb..b80fc6645f0 100644 --- a/xml/System.Collections.Immutable/ImmutableArray`1.xml +++ b/xml/System.Collections.Immutable/ImmutableArray`1.xml @@ -2351,16 +2351,7 @@ The zero-based index of the element to get. Gets or sets the element at the specified index in the read-only list. The element at the specified index in the read-only list. - - property. Visual Basic implements as a [default property](~/docs/visual-basic/language-reference/modifiers/default.md), which provides the same indexing functionality. - - ]]> - + To be added. Always thrown from the setter. Thrown if the property returns true. @@ -2984,19 +2975,7 @@ This member is an explicit interface member implementation. It can be used only The value to remove from the array. Throws in all cases. - - , the remains unchanged and no exception is thrown. - - - ## Examples The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - [!code-csharp[System.Collections.IList_Implementation#02](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.IList_Implementation/cs/Program.cs#02)] [!code-vb[System.Collections.IList_Implementation#02](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb#02)] - - ]]> - + To be added. Thrown in all cases.