language-servers/roc
1
0
Fork 0
mirror of https://github.com/roc-lang/roc.git synced 2025-09-26 13:29:12 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

update builtin comments

Browse source
This commit is contained in:
faldor20 2024-03-12 00:39:49 +10:00
parent be71514435
commit 23dd23c337
No known key found for this signature in database
GPG key ID: F2216079B890CD57
8 changed files with 96 additions and 96 deletions
Download patch file Download diff file Expand all files Collapse all files

10
crates/compiler/builtins/roc/Bool.roc
View file

@ -51,7 +51,7 @@ false = @Bool False
## gate. The infix operator `&&` can also be used as shorthand for
## `Bool.and`.
##
## ```
## ```roc
## expect (Bool.and Bool.true Bool.true) == Bool.true
## expect (Bool.true && Bool.true) == Bool.true
## expect (Bool.false && Bool.true) == Bool.false
@ -66,7 +66,7 @@ false = @Bool False
## In these languages the compiler will skip evaluating the expression after the
## first operator under certain circumstances. For example an expression like
## `enablePets && likesDogs user` would compile to.
## ```
## ```roc
## if enablePets then
## likesDogs user
## else
@ -80,7 +80,7 @@ and : Bool, Bool -> Bool
## Returns `Bool.true` when either input is a `Bool.true`. This is equivalent to
## the logic [OR](https://en.wikipedia.org/wiki/Logical_disjunction) gate.
## The infix operator `||` can also be used as shorthand for `Bool.or`.
## ```
## ```roc
## expect (Bool.or Bool.false Bool.true) == Bool.true
## expect (Bool.true || Bool.true) == Bool.true
## expect (Bool.false || Bool.true) == Bool.true
@ -98,7 +98,7 @@ or : Bool, Bool -> Bool
## Returns `Bool.false` when given `Bool.true`, and vice versa. This is
## equivalent to the logic [NOT](https://en.wikipedia.org/wiki/Negation)
## gate. The operator `!` can also be used as shorthand for `Bool.not`.
## ```
## ```roc
## expect (Bool.not Bool.false) == Bool.true
## expect (!Bool.false) == Bool.true
## ```
@ -111,7 +111,7 @@ not : Bool -> Bool
##
## **Note** that `isNotEq` does not accept arguments whose types contain
## functions.
## ```
## ```roc
## expect (Bool.isNotEq Bool.false Bool.true) == Bool.true
## expect (Bool.false != Bool.false) == Bool.false
## expect "Apples" != "Oranges"

4
crates/compiler/builtins/roc/Box.roc
View file

@ -10,13 +10,13 @@ interface Box
## the value from the stack to the heap. This may provide a performance
## optimization for advanced use cases with large values. A platform may require
## that some values are boxed.
## ```
## ```roc
## expect Box.unbox (Box.box "Stack Faster") == "Stack Faster"
## ```
box : a -> Box a
## Returns a boxed value.
## ```
## ```roc
## expect Box.unbox (Box.box "Stack Faster") == "Stack Faster"
## ```
unbox : Box a -> a

8
crates/compiler/builtins/roc/Decode.roc
View file

@ -59,7 +59,7 @@ DecodeError : [TooShort]
## This can be useful when creating a [custom](#custom) decoder or when
## using [fromBytesPartial](#fromBytesPartial). For example writing unit tests,
## such as;
## ```
## ```roc
## expect
## input = "\"hello\", " |> Str.toUtf8
## actual = Decode.fromBytesPartial input Json.json
@ -117,7 +117,7 @@ DecoderFormatting implements
## Build a custom [Decoder] function. For example the implementation of
## `decodeBool` could be defined as follows;
##
## ```
## ```roc
## decodeBool = Decode.custom \bytes, @Json {} ->
## when bytes is
## ['f', 'a', 'l', 's', 'e', ..] -> { result: Ok Bool.false, rest: List.dropFirst bytes 5 }
@ -132,7 +132,7 @@ decodeWith : List U8, Decoder val fmt, fmt -> DecodeResult val where fmt impleme
decodeWith = \bytes, @Decoder decode, fmt -> decode bytes fmt
## Decode a `List U8` utf-8 bytes and return a [DecodeResult](#DecodeResult)
## ```
## ```roc
## expect
## input = "\"hello\", " |> Str.toUtf8
## actual = Decode.fromBytesPartial input Json.json
@ -146,7 +146,7 @@ fromBytesPartial = \bytes, fmt -> decodeWith bytes decoder fmt
## Decode a `List U8` utf-8 bytes and return a [Result] with no leftover bytes
## expected. If successful returns `Ok val`, however, if there are bytes
## remaining returns `Err Leftover (List U8)`.
## ```
## ```roc
## expect
## input = "\"hello\", " |> Str.toUtf8
## actual = Decode.fromBytes input Json.json

48
crates/compiler/builtins/roc/Dict.roc
View file

@ -53,7 +53,7 @@ interface Dict
##
## Here's an example of a dictionary which uses a city's name as the key, and
## its population as the associated value.
## ```
## ```roc
## populationByCity =
## Dict.empty {}
## |> Dict.insert "London" 8_961_989
@ -74,7 +74,7 @@ interface Dict
## ## Removing
##
## We can remove an element from the dictionary, like so:
## ```
## ```roc
## populationByCity
## |> Dict.remove "Philadelphia"
## |> Dict.keys
@ -135,7 +135,7 @@ toInspectorDict = \dict ->
Inspect.apply (Inspect.dict dict walk Inspect.toInspector Inspect.toInspector) fmt
## Return an empty dictionary.
## ```
## ```roc
## emptyDict = Dict.empty {}
## ```
empty : {} -> Dict * *
@ -200,7 +200,7 @@ releaseExcessCapacity = \@Dict { buckets, data, maxBucketCapacity: originalMaxBu
@Dict { buckets, data, maxBucketCapacity: originalMaxBucketCapacity, maxLoadFactor, shifts }
## Returns the max number of elements the dictionary can hold before requiring a rehash.
## ```
## ```roc
## foodDict =
## Dict.empty {}
## |> Dict.insert "apple" "fruit"
@ -212,7 +212,7 @@ capacity = \@Dict { maxBucketCapacity } ->
maxBucketCapacity
## Returns a dictionary containing the key and value provided as input.
## ```
## ```roc
## expect
## Dict.single "A" "B"
## |> Bool.isEq (Dict.insert (Dict.empty {}) "A" "B")
@ -222,7 +222,7 @@ single = \k, v ->
insert (empty {}) k v
## Returns dictionary with the keys and values specified by the input [List].
## ```
## ```roc
## expect
## Dict.single 1 "One"
## |> Dict.insert 2 "Two"
@ -241,7 +241,7 @@ fromList = \data ->
List.walk data (empty {}) (\dict, (k, v) -> insert dict k v)
## Returns the number of values in the dictionary.
## ```
## ```roc
## expect
## Dict.empty {}
## |> Dict.insert "One" "A Song"
@ -255,7 +255,7 @@ len = \@Dict { data } ->
List.len data
## Check if the dictionary is empty.
## ```
## ```roc
## Dict.isEmpty (Dict.empty {} |> Dict.insert "key" 42)
##
## Dict.isEmpty (Dict.empty {})
@ -265,7 +265,7 @@ isEmpty = \@Dict { data } ->
List.isEmpty data
## Clears all elements from a dictionary keeping around the allocation if it isn't huge.
## ```
## ```roc
## songs =
## Dict.empty {}
## |> Dict.insert "One" "A Song"
@ -312,7 +312,7 @@ joinMap = \dict, transform ->
## Iterate through the keys and values in the dictionary and call the provided
## function with signature `state, k, v -> state` for each value, with an
## initial `state` value provided for the first call.
## ```
## ```roc
## expect
## Dict.empty {}
## |> Dict.insert "Apples" 12
@ -335,7 +335,7 @@ walk = \@Dict { data }, initialState, transform ->
##
## As such, it is typically better for performance to use this over [Dict.walk]
## if returning `Break` earlier than the last element is expected to be common.
## ```
## ```roc
## people =
## Dict.empty {}
## |> Dict.insert "Alice" 17
@ -358,7 +358,7 @@ walkUntil = \@Dict { data }, initialState, transform ->
## Run the given function on each key-value pair of a dictionary, and return
## a dictionary with just the pairs for which the function returned `Bool.true`.
## ```
## ```roc
## expect Dict.empty {}
## |> Dict.insert "Alice" 17
## |> Dict.insert "Bob" 18
@ -384,7 +384,7 @@ keepIfHelp = \@Dict dict, predicate, index, length ->
## Run the given function on each key-value pair of a dictionary, and return
## a dictionary with just the pairs for which the function returned `Bool.false`.
## ```
## ```roc
## expect Dict.empty {}
## |> Dict.insert "Alice" 17
## |> Dict.insert "Bob" 18
@ -399,7 +399,7 @@ dropIf = \dict, predicate ->
## Get the value for a given key. If there is a value for the specified key it
## will return [Ok value], otherwise return [Err KeyNotFound].
## ```
## ```roc
## dictionary =
## Dict.empty {}
## |> Dict.insert 1 "Apple"
@ -414,7 +414,7 @@ get = \dict, key ->
|> .result
## Check if the dictionary has a value for a specified key.
## ```
## ```roc
## expect
## Dict.empty {}
## |> Dict.insert 1234 "5678"
@ -428,7 +428,7 @@ contains = \dict, key ->
|> Result.isOk
## Insert a value into the dictionary at a specified key.
## ```
## ```roc
## expect
## Dict.empty {}
## |> Dict.insert "Apples" 12
@ -472,7 +472,7 @@ insertHelper = \buckets0, data0, bucketIndex0, distAndFingerprint0, key, value,
insertHelper buckets0 data0 bucketIndex1 distAndFingerprint1 key value maxBucketCapacity maxLoadFactor shifts
## Remove a value from the dictionary for a specified key.
## ```
## ```roc
## expect
## Dict.empty {}
## |> Dict.insert "Some" "Value"
@ -510,7 +510,7 @@ removeHelper = \buckets, bucketIndex, distAndFingerprint, data, key ->
## performance optimization for the use case of providing a default when a value
## is missing. This is more efficient than doing both a `Dict.get` and then a
## `Dict.insert` call, and supports being piped.
## ```
## ```roc
## alterValue : [Present Bool, Missing] -> [Present Bool, Missing]
## alterValue = \possibleValue ->
## when possibleValue is
@ -573,7 +573,7 @@ circularDist = \start, end, size ->
## Returns the keys and values of a dictionary as a [List].
## This requires allocating a temporary list, prefer using [Dict.toList] or [Dict.walk] instead.
## ```
## ```roc
## expect
## Dict.single 1 "One"
## |> Dict.insert 2 "Two"
@ -588,7 +588,7 @@ toList = \@Dict { data } ->
## Returns the keys of a dictionary as a [List].
## This requires allocating a temporary [List], prefer using [Dict.toList] or [Dict.walk] instead.
## ```
## ```roc
## expect
## Dict.single 1 "One"
## |> Dict.insert 2 "Two"
@ -603,7 +603,7 @@ keys = \@Dict { data } ->
## Returns the values of a dictionary as a [List].
## This requires allocating a temporary [List], prefer using [Dict.toList] or [Dict.walk] instead.
## ```
## ```roc
## expect
## Dict.single 1 "One"
## |> Dict.insert 2 "Two"
@ -621,7 +621,7 @@ values = \@Dict { data } ->
## both dictionaries will be combined. Note that where there are pairs
## with the same key, the value contained in the second input will be
## retained, and the value in the first input will be removed.
## ```
## ```roc
## first =
## Dict.single 1 "Not Me"
## |> Dict.insert 2 "And Me"
@ -650,7 +650,7 @@ insertAll = \xs, ys ->
## Combine two dictionaries by keeping the [intersection](https://en.wikipedia.org/wiki/Intersection_(set_theory))
## of all the key-value pairs. This means that we keep only those pairs
## that are in both dictionaries. Both the key and value must match to be kept.
## ```
## ```roc
## first =
## Dict.single 1 "Keep Me"
## |> Dict.insert 2 "And Me"
@ -691,7 +691,7 @@ keepShared = \xs0, ys0 ->
## using the [set difference](https://en.wikipedia.org/wiki/Complement_(set_theory)#Relative_complement)
## of the values. This means that we will be left with only those pairs that
## are in the first dictionary and whose keys are not in the second.
## ```
## ```roc
## first =
## Dict.single 1 "Keep Me"
## |> Dict.insert 2 "And Me"

6
crates/compiler/builtins/roc/Encode.roc
View file

@ -75,7 +75,7 @@ EncoderFormatting implements
## Creates a custom encoder from a given function.
##
## ```
## ```roc
## expect
## # Appends the byte 42
## customEncoder = Encode.custom (\bytes, _fmt -> List.append bytes 42)
@ -93,7 +93,7 @@ appendWith = \lst, @Encoder doEncoding, fmt -> doEncoding lst fmt
## Appends the encoded representation of a value to an existing list of bytes.
##
## ```
## ```roc
## expect
## actual = Encode.append [] { foo: 43 } Core.json
## expected = Str.toUtf8 """{"foo":43}"""
@ -105,7 +105,7 @@ append = \lst, val, fmt -> appendWith lst (toEncoder val) fmt
## Encodes a value to a list of bytes (`List U8`) according to the specified format.
##
## ```
## ```roc
## expect
## fooRec = { foo: 42 }
##

68
crates/compiler/builtins/roc/Num.roc
View file

@ -159,7 +159,7 @@ interface Num
## Represents a number that could be either an [Int] or a [Frac].
##
## This is useful for functions that can work on either, for example [Num.add], whose type is:
## ```
## ```roc
## add : Num a, Num a -> Num a
## ```
## The number 1.5 technically has the type `Num (Fraction *)`, so when you pass
@ -199,7 +199,7 @@ interface Num
##
## If this default of [I64] is not big enough for your purposes,
## you can add an `i128` to the end of the number literal, like so:
## ```
## ```roc
## Num.toStr 5_000_000_000i128
## ```
## This `i128` suffix specifies that you want this number literal to be
@ -268,7 +268,7 @@ Num range := range
##
## You can optionally put underscores in your [Int] literals.
## They have no effect on the number's value, but can make large numbers easier to read.
## ```
## ```roc
## 1_000_000
## ```
## Integers come in two flavors: *signed* and *unsigned*.
@ -335,14 +335,14 @@ Int range : Num (Integer range)
##
## If you don't specify a type, Roc will default to using [Dec] because it's
## the least error-prone overall. For example, suppose you write this:
## ```
## ```roc
## wasItPrecise = 0.1 + 0.2 == 0.3
## ```
## The value of `wasItPrecise` here will be `Bool.true`, because Roc uses [Dec]
## by default when there are no types specified.
##
## In contrast, suppose we use `f32` or `f64` for one of these numbers:
## ```
## ```roc
## wasItPrecise = 0.1f64 + 0.2 == 0.3
## ```
## Here, `wasItPrecise` will be `Bool.false` because the entire calculation will have
@ -528,11 +528,11 @@ tau = 2 * pi
# ------- Functions
## Convert a number to a [Str].
##
## ```
## ```roc
## Num.toStr 42
## ```
## Only [Frac] values will include a decimal point, and they will always include one.
## ```
## ```roc
## Num.toStr 4.2
## Num.toStr 4.0
## ```
@ -550,7 +550,7 @@ compare : Num a, Num a -> [LT, EQ, GT]
##
## If either argument is [*NaN*](Num.isNaN), returns `Bool.false` no matter what. (*NaN*
## is [defined to be unordered](https://en.wikipedia.org/wiki/NaN#Comparison_with_NaN).)
## ```
## ```roc
## 5
## |> Num.isLt 6
## ```
@ -562,7 +562,7 @@ isLt : Num a, Num a -> Bool
##
## If either argument is [*NaN*](Num.isNaN), returns `Bool.false` no matter what. (*NaN*
## is [defined to be unordered](https://en.wikipedia.org/wiki/NaN#Comparison_with_NaN).)
## ```
## ```roc
## 6
## |> Num.isGt 5
## ```
@ -625,14 +625,14 @@ toFrac : Num * -> Frac *
## Returns `Bool.true` if the [Frac] is not a number as defined by [IEEE-754](https://en.wikipedia.org/wiki/IEEE_754)
##
## ```
## ```roc
## Num.isNaN (0 / 0)
## ```
isNaN : Frac * -> Bool
## Returns `Bool.true` if the [Frac] is positive or negative infinity as defined by [IEEE-754](https://en.wikipedia.org/wiki/IEEE_754)
##
## ```
## ```roc
## Num.isInfinite (1 / 0)
##
## Num.isInfinite (-1 / 0)
@ -641,7 +641,7 @@ isInfinite : Frac * -> Bool
## Returns `Bool.true` if the [Frac] is not an infinity as defined by [IEEE-754](https://en.wikipedia.org/wiki/IEEE_754)
##
## ```
## ```roc
## Num.isFinite 42
## ```
isFinite : Frac * -> Bool
@ -651,7 +651,7 @@ isFinite : Frac * -> Bool
## * For a positive number, returns the same number.
## * For a negative number, returns the same number except positive.
## * For zero, returns zero.
## ```
## ```roc
## Num.abs 4
##
## Num.abs -2.5
@ -671,7 +671,7 @@ abs : Num a -> Num a
## Returns the absolute difference between two numbers.
##
## ```
## ```roc
## Num.absDiff 5 3
##
## Num.absDiff -3 5
@ -691,7 +691,7 @@ absDiff = \a, b ->
b - a
## Returns a negative number when given a positive one, and vice versa.
## ```
## ```roc
## Num.neg 5
##
## Num.neg -2.5
@ -716,13 +716,13 @@ neg : Num a -> Num a
## (To add an [Int] and a [Frac], first convert one so that they both have the same type. There are functions in this module that can convert both [Int] to [Frac] and the other way around.)
##
## `a + b` is shorthand for `Num.add a b`.
## ```
## ```roc
## 5 + 7
##
## Num.add 5 7
## ```
## `Num.add` can be convenient in pipelines.
## ```
## ```roc
## Frac.pi
## |> Num.add 1.0
## ```
@ -737,13 +737,13 @@ add : Num a, Num a -> Num a
## (To subtract an [Int] and a [Frac], first convert one so that they both have the same type. There are functions in this module that can convert both [Int] to [Frac] and the other way around.)
##
## `a - b` is shorthand for `Num.sub a b`.
## ```
## ```roc
## 7 - 5
##
## Num.sub 7 5
## ```
## `Num.sub` can be convenient in pipelines.
## ```
## ```roc
## Frac.pi
## |> Num.sub 2.0
## ```
@ -758,7 +758,7 @@ sub : Num a, Num a -> Num a
## (To multiply an [Int] and a [Frac], first convert one so that they both have the same type. There are functions in this module that can convert both [Int] to [Frac] and the other way around.)
##
## `a * b` is shorthand for `Num.mul a b`.
## ```
## ```roc
## 5 * 7
##
## Num.mul 5 7
@ -766,7 +766,7 @@ sub : Num a, Num a -> Num a
##
## `Num.mul` can be convenient in pipelines.
##
## ```
## ```roc
## Frac.pi
## |> Num.mul 2.0
## ```
@ -778,7 +778,7 @@ mul : Num a, Num a -> Num a
## Obtains the smaller between two numbers of the same type.
##
## ```
## ```roc
## Num.min 100 0
##
## Num.min 3.0 -3.0
@ -792,7 +792,7 @@ min = \a, b ->
## Obtains the greater between two numbers of the same type.
##
## ```
## ```roc
## Num.max 100 0
##
## Num.max 3.0 -3.0
@ -828,7 +828,7 @@ atan : Frac a -> Frac a
## > this standard, deviating from these rules has a significant performance
## > cost! Since the most common reason to choose [F64] or [F32] over [Dec] is
## > access to hardware-accelerated performance, Roc follows these rules exactly.
## ```
## ```roc
## Num.sqrt 4.0
##
## Num.sqrt 1.5
@ -877,13 +877,13 @@ logChecked = \x ->
##
## To divide an [Int] and a [Frac], first convert the [Int] to a [Frac] using
## one of the functions in this module like #toDec.
## ```
## ```roc
## 5.0 / 7.0
##
## Num.div 5 7
## ```
## `Num.div` can be convenient in pipelines.
## ```
## ```roc
## Num.pi
## |> Num.div 2.0
## ```
@ -912,7 +912,7 @@ divCeilChecked = \a, b ->
## Division by zero is undefined in mathematics. As such, you should make
## sure never to pass zero as the denominator to this function! If you do,
## it will crash.
## ```
## ```roc
## 5 // 7
##
## Num.divTrunc 5 7
@ -941,7 +941,7 @@ divTruncUnchecked : Int a, Int a -> Int a
## Obtains the remainder (truncating modulo) from the division of two integers.
##
## `a % b` is shorthand for `Num.rem a b`.
## ```
## ```roc
## 5 % 7
##
## Num.rem 5 7
@ -992,7 +992,7 @@ bitwiseNot = \n ->
##
## The least significant bits always become 0. This means that shifting left is
## like multiplying by factors of two for unsigned integers.
## ```
## ```roc
## shiftLeftBy 0b0000_0011 2 == 0b0000_1100
##
## 0b0000_0101 |> shiftLeftBy 2 == 0b0000_1100
@ -1003,7 +1003,7 @@ shiftLeftBy : Int a, U8 -> Int a
## Bitwise arithmetic shift of a number by another
##
## The most significant bits are copied from the current.
## ```
## ```roc
## shiftRightBy 0b0000_1100 2 == 0b0000_0011
##
## 0b0001_0100 |> shiftRightBy 2 == 0b0000_0101
@ -1017,7 +1017,7 @@ shiftRightBy : Int a, U8 -> Int a
##
## The most significant bits always become 0. This means that shifting right is
## like dividing by factors of two for unsigned integers.
## ```
## ```roc
## shiftRightZfBy 0b0010_1000 2 == 0b0000_1010
##
## 0b0010_1000 |> shiftRightZfBy 2 == 0b0000_1010
@ -1053,7 +1053,7 @@ powInt : Int a, Int a -> Int a
## Counts the number of most-significant (leading in a big-Endian sense) zeroes in an integer.
##
## ```
## ```roc
## Num.countLeadingZeroBits 0b0001_1100u8
##
## 3
@ -1066,7 +1066,7 @@ countLeadingZeroBits : Int a -> U8
## Counts the number of least-significant (trailing in a big-Endian sense) zeroes in an integer.
##
## ```
## ```roc
## Num.countTrailingZeroBits 0b0001_1100u8
##
## 2
@ -1079,7 +1079,7 @@ countTrailingZeroBits : Int a -> U8
## Counts the number of set bits in an integer.
##
## ```
## ```roc
## Num.countOneBits 0b0001_1100u8
##
## 3

14
crates/compiler/builtins/roc/Result.roc
View file

@ -7,7 +7,7 @@ interface Result
Result ok err : [Ok ok, Err err]
## Returns `Bool.true` if the result indicates a success, else returns `Bool.false`
## ```
## ```roc
## Result.isOk (Ok 5)
## ```
isOk : Result ok err -> Bool
@ -17,7 +17,7 @@ isOk = \result ->
Err _ -> Bool.false
## Returns `Bool.true` if the result indicates a failure, else returns `Bool.false`
## ```
## ```roc
## Result.isErr (Err "uh oh")
## ```
isErr : Result ok err -> Bool
@ -28,7 +28,7 @@ isErr = \result ->
## If the result is `Ok`, returns the value it holds. Otherwise, returns
## the given default value.
## ```
## ```roc
## Result.withDefault (Ok 7) 42
## Result.withDefault (Err "uh oh") 42
## ```
@ -41,7 +41,7 @@ withDefault = \result, default ->
## If the result is `Ok`, transforms the value it holds by running a conversion
## function on it. Then returns a new `Ok` holding the transformed value. If the
## result is `Err`, this has no effect. Use [mapErr] to transform an `Err`.
## ```
## ```roc
## Result.map (Ok 12) Num.neg
## Result.map (Err "yipes!") Num.neg
## ```
@ -57,7 +57,7 @@ map = \result, transform ->
## If the result is `Err`, transforms the value it holds by running a conversion
## function on it. Then returns a new `Err` holding the transformed value. If
## the result is `Ok`, this has no effect. Use [map] to transform an `Ok`.
## ```
## ```roc
## Result.mapErr (Err "yipes!") Str.isEmpty
## Result.mapErr (Ok 12) Str.isEmpty
## ```
@ -70,7 +70,7 @@ mapErr = \result, transform ->
## If the result is `Ok`, transforms the entire result by running a conversion
## function on the value the `Ok` holds. Then returns that new result. If the
## result is `Err`, this has no effect. Use `onErr` to transform an `Err`.
## ```
## ```roc
## Result.try (Ok -1) \num -> if num < 0 then Err "negative!" else Ok -num
## Result.try (Err "yipes!") \num -> if num < 0 then Err "negative!" else Ok -num
## ```
@ -83,7 +83,7 @@ try = \result, transform ->
## If the result is `Err`, transforms the entire result by running a conversion
## function on the value the `Err` holds. Then returns that new result. If the
## result is `Ok`, this has no effect. Use `try` to transform an `Ok`.
## ```
## ```roc
## Result.onErr (Ok 10) \errorNum -> Str.toU64 errorNum
## Result.onErr (Err "42") \errorNum -> Str.toU64 errorNum
## ```

34
crates/compiler/builtins/roc/Set.roc
View file

@ -68,7 +68,7 @@ toInspectorSet = \set ->
Inspect.apply (Inspect.set set walk Inspect.toInspector) fmt
## Creates a new empty `Set`.
## ```
## ```roc
## emptySet = Set.empty {}
## countValues = Set.len emptySet
##
@ -97,7 +97,7 @@ releaseExcessCapacity = \@Set dict ->
@Set (Dict.releaseExcessCapacity dict)
## Creates a new `Set` with a single value.
## ```
## ```roc
## singleItemSet = Set.single "Apple"
## countValues = Set.len singleItemSet
##
@ -108,7 +108,7 @@ single = \key ->
Dict.single key {} |> @Set
## Insert a value into a `Set`.
## ```
## ```roc
## fewItemSet =
## Set.empty {}
## |> Set.insert "Apple"
@ -141,7 +141,7 @@ expect
expected == actual
## Counts the number of values in a given `Set`.
## ```
## ```roc
## fewItemSet =
## Set.empty {}
## |> Set.insert "Apple"
@ -157,7 +157,7 @@ len = \@Set dict ->
Dict.len dict
## Returns the max number of elements the set can hold before requiring a rehash.
## ```
## ```roc
## foodSet =
## Set.empty {}
## |> Set.insert "apple"
@ -169,7 +169,7 @@ capacity = \@Set dict ->
Dict.capacity dict
## Check if the set is empty.
## ```
## ```roc
## Set.isEmpty (Set.empty {} |> Set.insert 42)
##
## Set.isEmpty (Set.empty {})
@ -191,7 +191,7 @@ expect
actual == 3
## Removes the value from the given `Set`.
## ```
## ```roc
## numbers =
## Set.empty {}
## |> Set.insert 10
@ -209,7 +209,7 @@ remove = \@Set dict, key ->
Dict.remove dict key |> @Set
## Test if a value is in the `Set`.
## ```
## ```roc
## Fruit : [Apple, Pear, Banana]
##
## fruit : Set Fruit
@ -228,7 +228,7 @@ contains = \@Set dict, key ->
Dict.contains dict key
## Retrieve the values in a `Set` as a `List`.
## ```
## ```roc
## numbers : Set U64
## numbers = Set.fromList [1,2,3,4,5]
##
@ -241,7 +241,7 @@ toList = \@Set dict ->
Dict.keys dict
## Create a `Set` from a `List` of values.
## ```
## ```roc
## values =
## Set.empty {}
## |> Set.insert Banana
@ -261,7 +261,7 @@ fromList = \list ->
## [union](https://en.wikipedia.org/wiki/Union_(set_theory))
## of all the values pairs. This means that all of the values in both `Set`s
## will be combined.
## ```
## ```roc
## set1 = Set.single Left
## set2 = Set.single Right
##
@ -274,7 +274,7 @@ union = \@Set dict1, @Set dict2 ->
## Combine two `Set`s by keeping the [intersection](https://en.wikipedia.org/wiki/Intersection_(set_theory))
## of all the values pairs. This means that we keep only those values that are
## in both `Set`s.
## ```
## ```roc
## set1 = Set.fromList [Left, Other]
## set2 = Set.fromList [Left, Right]
##
@ -288,7 +288,7 @@ intersection = \@Set dict1, @Set dict2 ->
## using the [set difference](https://en.wikipedia.org/wiki/Complement_(set_theory)#Relative_complement)
## of the values. This means that we will be left with only those values that
## are in the first and not in the second.
## ```
## ```roc
## first = Set.fromList [Left, Right, Up, Down]
## second = Set.fromList [Left, Right]
##
@ -299,7 +299,7 @@ difference = \@Set dict1, @Set dict2 ->
Dict.removeAll dict1 dict2 |> @Set
## Iterate through the values of a given `Set` and build a value.
## ```
## ```roc
## values = Set.fromList ["March", "April", "May"]
##
## startsWithLetterM = \month ->
@ -345,7 +345,7 @@ joinMap = \set, transform ->
## Iterate through the values of a given `Set` and build a value, can stop
## iterating part way through the collection.
## ```
## ```roc
## numbers = Set.fromList [1,2,3,4,5,6,42,7,8,9,10]
##
## find42 = \state, k ->
@ -364,7 +364,7 @@ walkUntil = \@Set dict, state, step ->
## Run the given function on each element in the `Set`, and return
## a `Set` with just the elements for which the function returned `Bool.true`.
## ```
## ```roc
## expect Set.fromList [1,2,3,4,5]
## |> Set.keepIf \k -> k >= 3
## |> Bool.isEq (Set.fromList [3,4,5])
@ -375,7 +375,7 @@ keepIf = \@Set dict, predicate ->
## Run the given function on each element in the `Set`, and return
## a `Set` with just the elements for which the function returned `Bool.false`.
## ```
## ```roc
## expect Set.fromList [1,2,3,4,5]
## |> Set.dropIf \k -> k >= 3
## |> Bool.isEq (Set.fromList [1,2])