Update examples for Standard.Base.Data.* (#1707)

distribution/std-lib/Standard/data/food_shop_inventory.csv

@@ -0,0 +1,10 @@
+item_name                  , price , stock
+Pavlova Cake (Whole)       , 10.50 , 10
+Gruyere (Wheel)            , 50    , 3
+Strawberries (Punnett)     , 4.50  , 50
+Tomatoes (Whole)           , 0.5   , 100
+Tomato and Egg Sandwich    , 1.75  , 20
+Lobster Thermidor          , 15.50 , 10
+Syrniki                    , 1.99  , 25
+Bacon and Sausage Sandwich , 1.75  , 15
+

distribution/std-lib/Standard/src/Base.enso

@@ -41,7 +41,7 @@ from Standard.Base.Data.Number.Extensions export all hiding Math, String, Double
 from Standard.Base.Data.Noise export all hiding Noise
 from Standard.Base.Data.Pair export Pair
 from Standard.Base.Data.Range export Range
-from Standard.Base.Data.Text.Extensions export Text
+from Standard.Base.Data.Text.Extensions export Text, Split_Kind
 from Standard.Base.Error.Common export all
 from Standard.Base.Error.Extensions export all
 from Standard.Base.Meta.Enso_Project export all

distribution/std-lib/Standard/src/Base/Data/Any/Extensions.enso

@@ -23,8 +23,13 @@ from Standard.Base import all
      their own equality operations that will be more efficient than these.
 
    > Example
-     Checking if 1 is equal to 2.
-         1 == 2
+     Checking if the variable `a` is equal to `147`.
+
+         from Standard.Base import all
+
+         example_equality =
+             a = 7 * 21
+             a == 147
 Any.== : Any -> Boolean
 Any.== that = if Meta.is_same_object this that then True else
     this_meta = Meta.meta this
@@ -57,8 +62,13 @@ Any.== that = if Meta.is_same_object this that then True else
      satisfy universal equality, as described in the documentation for `Any.==`.
 
    > Example
-     Checking if 1 is not equal to 2.
-         1 != 2
+     Checking if the variable `a` is not equal to `147`.
+
+         from Standard.Base import all
+
+         example_inequality =
+             a = 7 * 21
+             a != 147
 Any.!= : Any -> Boolean
 Any.!= that = (this == that).not
 
@@ -75,8 +85,13 @@ Any.!= that = (this == that).not
      please ensure that it is semantically equivalent to using `.compare_to`.
 
    > Example
-     Checking if 1 is greater than 10.
-         1 > 10
+     Checking if the variable `a` is greater than `147`.
+
+         from Standard.Base import all
+
+         example_greater =
+             a = 7 * 28
+             a > 147
 Any.> : Any -> Boolean
 Any.> that = this.compare_to that == Ordering.Greater
 
@@ -94,8 +109,13 @@ Any.> that = this.compare_to that == Ordering.Greater
      greater than and equal to operations.
 
    > Example
-     Checking if 1 is greater than or equal to 10.
-         1 >= 10
+     Checking if the variable `a` is greater than or equal to `147`.
+
+         from Standard.Base import all
+
+         example_greater_eq =
+             a = 6 * 21
+             a >= 147
 Any.>= : Any -> Boolean
 Any.>= that = (this > that) || (this == that)
 
@@ -112,8 +132,13 @@ Any.>= that = (this > that) || (this == that)
      please ensure that it is semantically equivalent to using `.compare_to`.
 
    > Example
-     Checking if 1 is less than 10.
-         1 < 10
+     Checking if the variable `a` is less than `147`.
+
+         from Standard.Base import all
+
+         example_less =
+             a = 7 * 21
+             a < 147
 Any.< : Any -> Boolean
 Any.< that = this.compare_to that == Ordering.Less
 
@@ -131,8 +156,13 @@ Any.< that = this.compare_to that == Ordering.Less
      less than than and equal to operations.
 
    > Example
-     Checking if 1 is less than or equal to 10.
-         1 <= 10
+     Checking if the variable `a` is less than or equal to `147`.
+
+         from Standard.Base import all
+
+         example_less_eq =
+             a = 7 * 21
+             a < 147
 Any.<= : Any -> Boolean
 Any.<= that = (this < that) || (this == that)
 
@@ -143,22 +173,28 @@ Any.<= that = (this < that) || (this == that)
 
    > Example
      Checking if the value 1 is nothing.
+
          1.is_nothing
 Any.is_nothing : Boolean
 Any.is_nothing = case this of
     Nothing -> True
     _ -> False
 
-## Executes the provided handler on a dataflow error, or returns a non-error
-   value unchanged.
+## Executes the provided handler on an error, or returns a non-error value
+   unchanged.
 
    Arguments:
    - handler: The function to call on this if it is an error value. By default
      this is identity.
 
    > Example
      Catching an erroneous value and getting the length of its message.
-       (Time.Time_Error "Message").catch (err -> err.error_message.length)
+
+         from Standard.Base import all
+
+         example_catch =
+             error = Error.throw "My message"
+             error.catch (err -> err.length)
 Any.catch : (Error -> Any) -> Any
 Any.catch (handler = x->x) = this.catch_primitive handler
 
@@ -171,12 +207,24 @@ Any.catch (handler = x->x) = this.catch_primitive handler
    is an error, the error is transformed using the provided function.
 
    > Example
-     Wrapping an error value.
-       map.get "x" . map_error (_ -> ElementNotFound "x")
+     Transforming an error value to provide more information.
+
+         from Standard.Base import all
+         from Standard.Examples import Example_Error_Type
+
+         example_map_error =
+            my_map = Map.empty
+            error = my_map.get "x"
+            error.map_error (_ -> Example_Error_Type "x is missing")
 Any.map_error : (Error -> Error) -> Any
 Any.map_error _ = this
 
 ## Checks if `this` is an error.
+
+   > Example
+     Checking if the provided value is an error.
+
+         1.is_error
 Any.is_error : Boolean
 Any.is_error = False
 
@@ -192,6 +240,7 @@ Any.is_error = False
 
    > Example
      Applying a function to a block.
+
          (x -> x + 1) <|
             y = 1 ^ 3
             3 + y
@@ -214,6 +263,7 @@ Any.<| ~argument = this argument
    > Example
      Applying multiple functions in a pipeline to compute a number and transform
      it to text.
+
          1 |> (* 2) |> (/ 100) |> .to_text
 Any.|> : (Any -> Any) -> Any
 Any.|> ~function = function this
@@ -226,6 +276,7 @@ Any.|> ~function = function this
 
    > Example
      Multiply by 2 and then add 1 as a function applied to 2.
+
          (+1 << *2) 2
 Any.<< : (Any -> Any) -> (Any -> Any) -> Any -> Any
 Any.<< ~that = x -> this (that x)
@@ -238,6 +289,7 @@ Any.<< ~that = x -> this (that x)
 
    > Example
      Add one and then multiply by two as a function applied to 2.
+
          (+1 >> *2) 2
 Any.>> : (Any -> Any) -> (Any -> Any) -> Any -> Any
 Any.>> ~that = x -> that (this x)
@@ -256,6 +308,7 @@ Any.>> ~that = x -> that (this x)
 
    > Example
      Converting the number `2` into visualization data.
+
          2.to_default_visualization_data
 Any.to_default_visualization_data : Text
 Any.to_default_visualization_data = this.to_json.to_text

distribution/std-lib/Standard/src/Base/Data/Array/Extensions.enso

@@ -11,6 +11,7 @@ from Standard.Base import all
 
    > Example
      Converting an array to its default visualization representation.
+
          [1, 2, 3, 4].to_array.to_default_visualization_data
 Array.to_default_visualization_data : Text
 Array.to_default_visualization_data =

distribution/std-lib/Standard/src/Base/Data/Interval.enso

@@ -8,38 +8,52 @@ export Standard.Base.Data.Interval.Bound
 
    > Example
      Create the bounds-exclusive range from 1 to 5.
-         Interval.exclusive 1 5
+
+         import Standard.Base.Data.Interval
+
+         example_exclusive = Interval.exclusive 1 5
 exclusive : Any -> Any -> Interval
 exclusive start end = Interval (Bound.Exclusive start) (Bound.Exclusive end)
 
 ## Creates an interval that excludes its lower bound.
 
    > Example
      Create the start-exclusive range from 1 to 5.
-         Interval.start_exclusive 1 5
+
+         import Standard.Base.Data.Interval
+
+         example_start_exclusive = Interval.start_exclusive 1 5
 start_exclusive : Any -> Any -> Interval
 start_exclusive start end = Interval (Bound.Exclusive start) (Bound.Inclusive end)
 
 ## Creates an interval that excludes its upper bound.
 
    > Example
      Create the end-exclusive range from 1 to 5.
-         Interval.end_exclusive 1 5
+
+         import Standard.Base.Data.Interval
+
+         example_end_exclusive = Interval.end_exclusive 1 5
 end_exclusive : Any -> Any -> Interval
 end_exclusive start end = Interval (Bound.Inclusive start) (Bound.Exclusive end)
 
-## Creates an interval that includes its upper bound.
+## Creates an interval that includes both of its bounds.
 
    > Example
      Create the inclusive range from 1 to 5.
-         Interval.inclusive 1 5
+
+         import Standard.Base.Data.Interval
+
+         example_inclusive = Interval.inclusive 1 5
 inclusive : Any -> Any -> Interval
 inclusive start end = Interval (Bound.Inclusive start) (Bound.Inclusive end)
 
 ## An interval type
 type Interval
 
-    ## A type representing an interval over orderable types.
+    ## PRIVATE
+
+       A type representing an interval over orderable types.
 
        Arguments:
        - start: The start of the interval.
@@ -53,7 +67,10 @@ type Interval
 
        > Example
          Checking if the interval 1 to 5 contains 7.
-             (Interval.inclusive 1 5) . contains 7
+
+             import Standard.Base.Data.Interval
+
+             example_contains = (Interval.inclusive 1 5) . contains 7
     contains : Any -> Boolean
     contains that = if this.start.n > this.end.n then False else
         case this.start of
@@ -68,7 +85,10 @@ type Interval
 
        > Example
          Check if the interval from 0 to 0 is empty.
-             Interval.inclusive 0 0 . is_empty
+
+             import Standard.Base.Data.Interval
+
+             example_is_empty = Interval.inclusive 0 0 . is_empty
     is_empty : Boolean
     is_empty = case this.start of
         Bound.Exclusive s -> case this.end of
@@ -82,7 +102,10 @@ type Interval
 
        > Example
          Check if the interval from 0 to 1 is not empty.
-             Interval.inclusive 0 1 . not_empty
+
+             import Standard.Base.Data.Interval
+
+             example_not_empty = Interval.inclusive 0 1 . not_empty
     not_empty : Boolean
     not_empty = this.is_empty.not
 

distribution/std-lib/Standard/src/Base/Data/Interval/Bound.enso

@@ -12,7 +12,10 @@ type Bound
 
        > Example
          Create a bound that includes the value 2.
-             Inclusive 2
+
+             import Standard.Base.Data.Interval.Bound
+
+             example_bound_inclusive = Bound.Inclusive 2
     type Inclusive n
 
     ## A bound that excludes the value `n`.
@@ -22,5 +25,8 @@ type Bound
 
        > Example
          Create a bound that excludes the value 2.
-             Exclusive 2
+
+             import Standard.Base.Data.Interval.Bound
+
+             example_bound_exclusive = Bound.Exclusive 2.
     type Exclusive n