DOCSP-48356: skipwhile & takewhile (#536)

* DOCSP-48356: skipwhile & takewhile

* copyable false

* RStam tech review

* RStam tech review 2

(cherry picked from commit c2adeca)

Author: rustagir

source/fundamentals/linq.txt

@@ -248,6 +248,44 @@ The result of the preceding example contains the following documents:
     { "name" : "Crystal Room", "cuisine" : "Italian" }
     { "name" : "Forlinis Restaurant", "cuisine" : "Italian" }
 
+.. _csharp-linq-takewhile:
+
+Limit on a Condition
+````````````````````
+
+You can use the ``TakeWhile()`` LINQ method in a ``Select()`` projection
+to return array field elements while a specified condition is true, then
+skip the remaining elements.
+
+This example uses the following ``Student`` class to model documents
+that contain an array field ``Grades``:
+
+.. code-block:: csharp
+
+   public class Student
+   {
+       public ObjectId Id { get; set; }
+       public string Name { get; set; }
+       public int[] Grades { get; set; }
+   }
+
+The following code shows how to use the ``TakeWhile()`` method to return
+any ``Grades`` array elements that are greater than ``90`` and skip the
+rest of the array:
+
+.. code-block:: csharp
+
+   var query = queryableCollection
+       .Select(s => s.Grades.TakeWhile(g => g > 90).ToArray());
+
+The results might resemble the following arrays:
+
+.. code-block:: json
+   :copyable: false
+
+   [92, 97]
+   [100, 95, 91]
+
 $sample
 ~~~~~~~
 
@@ -301,6 +339,44 @@ returns the rest. The result contains the following documents:
    { "name" : "Forlinis Restaurant", "cuisine" : "Italian" }
    ...
 
+.. _csharp-linq-skipwhile:
+
+Skip on a Condition
+```````````````````
+
+You can use the ``SkipWhile()`` LINQ method in a ``Select()`` projection
+to skip array field elements while a specified condition is true, then
+return the remaining elements.
+
+This example uses the following ``Student`` class to model documents
+that contain an array field ``Grades``:
+
+.. code-block:: csharp
+
+   public class Student
+   {
+       public ObjectId Id { get; set; }
+       public string Name { get; set; }
+       public int[] Grades { get; set; }
+   }
+
+The following code shows how to use the ``SkipWhile()`` method to skip
+any ``Grades`` array elements that are less than ``75`` and return the
+rest of the array:
+
+.. code-block:: csharp
+
+   var query = queryableCollection
+       .Select(s => s.Grades.SkipWhile(g => g < 75).ToArray());
+
+The results might resemble the following arrays:
+
+.. code-block:: json
+   :copyable: false
+
+   [80, 90, 70, 83]
+   [79, 100, 85, 73]
+
 $unwind
 ~~~~~~~
 
@@ -346,7 +422,7 @@ following documents:
    { "date" : ISODate("2012-05-17T00:00:00Z"), "grade" : "A", "score" : 11 }
 
 Nested Statements
-+++++++++++++++++
+`````````````````
 
 You can chain or nest ``Select`` and ``SelectMany`` statements to unwind nested
 arrays. Consider a collection that contains documents with a **new** schema. These
@@ -558,7 +634,7 @@ or the ``GroupJoin()`` method. The following sections show how to perform a
 ``$lookup`` by using each method.
 
 Lookup()
-++++++++
+````````
 
 The following code specifies a ``$lookup`` stage by using the ``Lookup()``
 method. This example joins documents from the ``reviews`` collection to
@@ -768,7 +844,7 @@ collection:
    throw an error.
 
 $bitAnd
-+++++++
+```````
 
 The ``$bitAnd`` aggregation operator performs a bitwise AND operation on the given
 arguments. You can use the ``$bitAnd`` operator by connecting two or more 
@@ -985,12 +1061,20 @@ The following are some methods supported by the {+driver-long+} implementation o
    * - ``Skip``
      - Skips over a specified number of documents and returns the rest of the results
 
+   * - ``SkipWhile`` (only in ``Select`` projections)
+     - Skips over array elements while a condition is true and returns
+       the remaining elements
+
    * - ``Sum``
      - Returns the sum of the values in a specified field
 
    * - ``Take``
      - Specifies the number of results to return
 
+   * - ``TakeWhile`` (only in ``Select`` projections)
+     - Returns array elements while a condition is true and skips
+       the remaining elements
+
    * - ``Where``
      - Returns all documents that match your specified criteria
 
@@ -1079,4 +1163,5 @@ API Documentation
 For a complete list of supported LINQ methods, see the following API documentation:
 
 - `LINQ <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Linq.html>`__
-- `MongoQueryable <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Linq.MongoQueryable.html>`__
+- `MongoQueryable
+  <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Linq.MongoQueryable.html>`__

source/whats-new.txt

@@ -64,7 +64,9 @@ The 3.3 driver release includes the following new features:
 - Adds the following LINQ features:
 
   - Support for the ``SkipWhile()`` and ``TakeWhile()`` LINQ
-    aggregation methods.
+    aggregation methods. To learn more, see the
+    :ref:`csharp-linq-skipwhile` and :ref:`csharp-linq-takewhile`
+    sections of the LINQ guide.
 
   - Support for the ``$sigmoid`` expression in LINQ queries.