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

Merge pull request #5450 from fdbeirao/docs-wording-consistency

Browse source 
Improve docs wording consistency and fix minor typos
This commit is contained in:
Anton-4 2023-05-26 16:33:01 +02:00 • committed by GitHub
commit 82743b24cd
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 74 additions and 73 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -2,7 +2,7 @@ interface Box
exposes [box, unbox]
imports []
## Allocate a value on the heap. Boxing is an expensive process as it copies
## Allocates a value on the heap. Boxing is an expensive process as it copies
## 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.

3
crates/compiler/builtins/roc/List.roc
View file

@ -72,7 +72,8 @@ interface List
Num.{ Nat, Num, Int },
]
## Types
## ## Types
##
## A sequential list of values.
## ```
## [1, 2, 3] # a list of numbers

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

@ -233,7 +233,7 @@ Num range := range
##
## [I8] is a signed integer that takes up 8 bits. The `I` is for Integer, since
## integers in mathematics are signed by default. Because it has 8 bits just
## like [U8], it can store 256 numbers (still 2^16), but because it is signed,
## like [U8], it can store 256 numbers (still 2^8), but because it is signed,
## the range is different. Its 256 numbers range from -128 to 127.
##
## Here are some other examples:
@ -283,7 +283,7 @@ Num range := range
## general trade-offs are:
##
## * Larger integer sizes can represent a wider range of numbers. If you absolutely need to represent numbers in a certain range, make sure to pick an integer size that can hold them!
## * Smaller integer sizes take up less memory. This savings rarely matters in variables and function arguments, but the sizes of integers that you use in data structures can add up. This can also affect whether those data structures fit in [cache lines](https://en.wikipedia.org/wiki/CPU_cache#Cache_performance), which can be a performance bottleneck.
## * Smaller integer sizes take up less memory. These savings rarely matter in variables and function arguments, but the sizes of integers that you use in data structures can add up. This can also affect whether those data structures fit in [cache lines](https://en.wikipedia.org/wiki/CPU_cache#Cache_performance), which can be a performance bottleneck.
## * Certain CPUs work faster on some numeric sizes than others. If the CPU is taking too long to run numeric calculations, you may find a performance improvement by experimenting with numeric sizes that are larger than otherwise necessary. However, in practice, doing this typically degrades overall performance, so be careful to measure properly!
##
## Here are the different fixed size integer types:
@ -327,7 +327,7 @@ Num range := range
##
## A common use for [Nat] is to store the length ("len" for short) of a
## collection like a [List]. 64-bit systems can represent longer
## lists in memory than 32-bit systems can, which is why the length of a list
## lists in memory than 32-bit systems, which is why the length of a list
## is represented as a [Nat] in Roc.
##
## If any operation would result in an [Int] that is either too big
@ -647,7 +647,7 @@ isInfinite : Frac * -> Bool
## ```
isFinite : Frac * -> Bool
## Return the absolute value of the number.
## Returns the absolute value of the number.
##
## * For a positive number, returns the same number.
## * For a negative number, returns the same number except positive.
@ -670,7 +670,7 @@ isFinite : Frac * -> Bool
## Calling this on an unsigned integer (like [U32] or [U64]) never does anything.
abs : Num a -> Num a
## Return the absolute difference between two numbers.
## Returns the absolute difference between two numbers.
##
## ```
## Num.absDiff 5 3
@ -691,7 +691,7 @@ absDiff = \a, b ->
else
b - a
## Return a negative number when given a positive one, and vice versa.
## Returns a negative number when given a positive one, and vice versa.
## ```
## Num.neg 5
##
@ -712,7 +712,7 @@ absDiff = \a, b ->
## (It will never crash when given a [Frac], however, because of how floating point numbers represent positive and negative numbers.)
neg : Num a -> Num a
## Add two numbers of the same type.
## Adds two numbers of the same type.
##
## (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.)
##
@ -733,7 +733,7 @@ neg : Num a -> Num a
## ∞ or -∞. For all other number types, overflow results in a panic.
add : Num a, Num a -> Num a
## Subtract two numbers of the same type.
## Subtracts two numbers of the same type.
##
## (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.)
##
@ -754,7 +754,7 @@ add : Num a, Num a -> Num a
## ∞ or -∞. For all other number types, overflow results in a panic.
sub : Num a, Num a -> Num a
## Multiply two numbers of the same type.
## Multiplies two numbers of the same type.
##
## (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.)
##
@ -833,7 +833,7 @@ logChecked = \x ->
else
Ok (Num.log x)
## Divide one [Frac] by another.
## Divides one [Frac] by another.
##
## `a / b` is shorthand for `Num.div a b`.
##
@ -882,12 +882,12 @@ divCeilChecked = \a, b ->
else
Ok (Num.divCeil a b)
## Divide two integers, truncating the result towards zero.
## Divides two integers, truncating the result towards zero.
##
## `a // b` is shorthand for `Num.divTrunc a b`.
##
## Division by zero is undefined in mathematics. As such, you should make
## sure never to pass zero as the denomaintor to this function! If you do,
## sure never to pass zero as the denominator to this function! If you do,
## it will crash.
## ```
## 5 // 7
@ -907,7 +907,7 @@ divTruncChecked = \a, b ->
else
Ok (Num.divTrunc a b)
## Obtain the remainder (truncating modulo) from the division of two integers.
## Obtains the remainder (truncating modulo) from the division of two integers.
##
## `a % b` is shorthand for `Num.rem a b`.
## ```
@ -1046,7 +1046,7 @@ countOneBits : Int a -> Nat
addWrap : Int range, Int range -> Int range
## Add two numbers, clamping on the maximum representable number rather than
## Adds two numbers, clamping on the maximum representable number rather than
## overflowing.
##
## This is the same as [Num.add] except for the saturating behavior if the
@ -1055,7 +1055,7 @@ addWrap : Int range, Int range -> Int range
## yield 255, the maximum value of a `U8`.
addSaturated : Num a, Num a -> Num a
## Add two numbers and check for overflow.
## Adds two numbers and checks for overflow.
##
## This is the same as [Num.add] except if the operation overflows, instead of
## panicking or returning ∞ or -∞, it will return `Err Overflow`.
@ -1072,7 +1072,7 @@ addCheckedLowlevel : Num a, Num a -> { b : Bool, a : Num a }
subWrap : Int range, Int range -> Int range
## Subtract two numbers, clamping on the minimum representable number rather
## Subtracts two numbers, clamping on the minimum representable number rather
## than overflowing.
##
## This is the same as [Num.sub] except for the saturating behavior if the
@ -1081,7 +1081,7 @@ subWrap : Int range, Int range -> Int range
## yield 0, the minimum value of a `U8`.
subSaturated : Num a, Num a -> Num a
## Subtract two numbers and check for overflow.
## Subtracts two numbers and checks for overflow.
##
## This is the same as [Num.sub] except if the operation overflows, instead of
## panicking or returning ∞ or -∞, it will return `Err Overflow`.
@ -1098,14 +1098,14 @@ subCheckedLowlevel : Num a, Num a -> { b : Bool, a : Num a }
mulWrap : Int range, Int range -> Int range
## Multiply two numbers, clamping on the maximum representable number rather than
## Multiplies two numbers, clamping on the maximum representable number rather than
## overflowing.
##
## This is the same as [Num.mul] except for the saturating behavior if the
## addition is to overflow.
mulSaturated : Num a, Num a -> Num a
## Multiply two numbers and check for overflow.
## Multiplies two numbers and checks for overflow.
##
## This is the same as [Num.mul] except if the operation overflows, instead of
## panicking or returning ∞ or -∞, it will return `Err Overflow`.
@ -1120,8 +1120,8 @@ mulChecked = \a, b ->
mulCheckedLowlevel : Num a, Num a -> { b : Bool, a : Num a }
## The lowest number that can be stored in an [I8] without underflowing its
## available memory and crashing.
## Returns the lowest number that can be stored in an [I8] without underflowing
## its available memory and crashing.
##
## For reference, this number is `-128`.
##
@ -1130,8 +1130,8 @@ mulCheckedLowlevel : Num a, Num a -> { b : Bool, a : Num a }
minI8 : I8
minI8 = -128i8
## The highest number that can be stored in an [I8] without overflowing its
## available memory and crashing.
## Returns the highest number that can be stored in an [I8] without overflowing
## its available memory and crashing.
##
## For reference, this number is `127`.
##
@ -1140,8 +1140,8 @@ minI8 = -128i8
maxI8 : I8
maxI8 = 127i8
## The lowest number that can be stored in a [U8] without underflowing its
## available memory and crashing.
## Returns the lowest number that can be stored in a [U8] without underflowing
## its available memory and crashing.
##
## For reference, this number is zero, because [U8] is
## [unsigned](https://en.wikipedia.org/wiki/Signed_number_representations),
@ -1150,15 +1150,15 @@ maxI8 = 127i8
minU8 : U8
minU8 = 0u8
## The highest number that can be stored in a [U8] without overflowing its
## available memory and crashing.
## Returns the highest number that can be stored in a [U8] without overflowing
## its available memory and crashing.
##
## For reference, this number is `255`.
maxU8 : U8
maxU8 = 255u8
## The lowest number that can be stored in an [I16] without underflowing its
## available memory and crashing.
## Returns the lowest number that can be stored in an [I16] without underflowing
## its available memory and crashing.
##
## For reference, this number is `-32_768`.
##
@ -1167,8 +1167,8 @@ maxU8 = 255u8
minI16 : I16
minI16 = -32768i16
## The highest number that can be stored in an [I16] without overflowing its
## available memory and crashing.
## Returns the highest number that can be stored in an [I16] without overflowing
## its available memory and crashing.
##
## For reference, this number is `32_767`.
##
@ -1177,8 +1177,8 @@ minI16 = -32768i16
maxI16 : I16
maxI16 = 32767i16
## The lowest number that can be stored in a [U16] without underflowing its
## available memory and crashing.
## Returns the lowest number that can be stored in a [U16] without underflowing
## its available memory and crashing.
##
## For reference, this number is zero, because [U16] is
## [unsigned](https://en.wikipedia.org/wiki/Signed_number_representations),
@ -1187,15 +1187,15 @@ maxI16 = 32767i16
minU16 : U16
minU16 = 0u16
## The highest number that can be stored in a [U16] without overflowing its
## available memory and crashing.
## Returns the highest number that can be stored in a [U16] without overflowing
## its available memory and crashing.
##
## For reference, this number is `65_535`.
maxU16 : U16
maxU16 = 65535u16
## The lowest number that can be stored in an [I32] without underflowing its
## available memory and crashing.
## Returns the lowest number that can be stored in an [I32] without underflowing
## its available memory and crashing.
##
## For reference, this number is `-2_147_483_648`.
##
@ -1204,8 +1204,8 @@ maxU16 = 65535u16
minI32 : I32
minI32 = -2147483648
## The highest number that can be stored in an [I32] without overflowing its
## available memory and crashing.
## Returns the highest number that can be stored in an [I32] without overflowing
## its available memory and crashing.
##
## For reference, this number is `2_147_483_647`,
## which is over 2 million.
@ -1215,8 +1215,8 @@ minI32 = -2147483648
maxI32 : I32
maxI32 = 2147483647
## The lowest number that can be stored in a [U32] without underflowing its
## available memory and crashing.
## Returns the lowest number that can be stored in a [U32] without underflowing
## its available memory and crashing.
##
## For reference, this number is zero, because [U32] is
## [unsigned](https://en.wikipedia.org/wiki/Signed_number_representations),
@ -1225,15 +1225,15 @@ maxI32 = 2147483647
minU32 : U32
minU32 = 0
## The highest number that can be stored in a [U32] without overflowing its
## available memory and crashing.
## Returns the highest number that can be stored in a [U32] without overflowing
## its available memory and crashing.
##
## For reference, this number is `4_294_967_295`.
maxU32 : U32
maxU32 = 4294967295
## The lowest number that can be stored in an [I64] without underflowing its
## available memory and crashing.
## Returns the lowest number that can be stored in an [I64] without underflowing
## its available memory and crashing.
##
## For reference, this number is `-9_223_372_036_854_775_808`,
## which is under 9 quintillion.
@ -1243,8 +1243,8 @@ maxU32 = 4294967295
minI64 : I64
minI64 = -9223372036854775808
## The highest number that can be stored in an [I64] without overflowing its
## available memory and crashing.
## Returns the highest number that can be stored in an [I64] without overflowing
## its available memory and crashing.
##
## For reference, this number is `9_223_372_036_854_775_807`,
## which is over 9 quintillion.
@ -1254,8 +1254,8 @@ minI64 = -9223372036854775808
maxI64 : I64
maxI64 = 9223372036854775807
## The lowest number that can be stored in a [U64] without underflowing its
## available memory and crashing.
## Returns the lowest number that can be stored in a [U64] without underflowing
## its available memory and crashing.
##
## For reference, this number is zero, because [U64] is
## [unsigned](https://en.wikipedia.org/wiki/Signed_number_representations),
@ -1264,16 +1264,16 @@ maxI64 = 9223372036854775807
minU64 : U64
minU64 = 0
## The highest number that can be stored in a [U64] without overflowing its
## available memory and crashing.
## Returns the highest number that can be stored in a [U64] without overflowing
## its available memory and crashing.
##
## For reference, this number is `18_446_744_073_709_551_615`,
## which is over 18 quintillion.
maxU64 : U64
maxU64 = 18446744073709551615
## The lowest number that can be stored in an [I128] without underflowing its
## available memory and crashing.
## Returns the lowest number that can be stored in an [I128] without underflowing
## its available memory and crashing.
##
## For reference, this number is `-170_141_183_460_469_231_731_687_303_715_884_105_728`.
## which is under 170 undecillion.
@ -1283,8 +1283,8 @@ maxU64 = 18446744073709551615
minI128 : I128
minI128 = -170141183460469231731687303715884105728
## The highest number that can be stored in an [I128] without overflowing its
## available memory and crashing.
## Returns the highest number that can be stored in an [I128] without overflowing
## its available memory and crashing.
##
## For reference, this number is `170_141_183_460_469_231_731_687_303_715_884_105_727`,
## which is over 170 undecillion.
@ -1294,8 +1294,8 @@ minI128 = -170141183460469231731687303715884105728
maxI128 : I128
maxI128 = 170141183460469231731687303715884105727
## The lowest number that can be stored in a [U128] without underflowing its
## available memory and crashing.
## Returns the lowest number that can be stored in a [U128] without underflowing
## its available memory and crashing.
##
## For reference, this number is zero, because [U128] is
## [unsigned](https://en.wikipedia.org/wiki/Signed_number_representations),
@ -1304,8 +1304,8 @@ maxI128 = 170141183460469231731687303715884105727
minU128 : U128
minU128 = 0
## The highest number that can be stored in a [U128] without overflowing its
## available memory and crashing.
## Returns the highest number that can be stored in a [U128] without overflowing
## its available memory and crashing.
##
## For reference, this number is `340_282_366_920_938_463_463_374_607_431_768_211_455`,
## which is over 340 undecillion.
@ -1337,7 +1337,7 @@ toU32 : Int * -> U32
toU64 : Int * -> U64
toU128 : Int * -> U128
## Convert an [Int] to a [Nat]. If the given number doesn't fit in [Nat], it will be truncated.
## Converts an [Int] to a [Nat]. If the given number doesn't fit in [Nat], it will be truncated.
## Since [Nat] has a different maximum number depending on the system you're building
## for, this may give a different answer on different systems.
##

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

@ -6,7 +6,7 @@ interface Result
## okay, or else there was an error of some sort.
Result ok err : [Ok ok, Err err]
## Return `Bool.true` if the result indicates a success, else return `Bool.false`
## Returns `Bool.true` if the result indicates a success, else returns `Bool.false`
## ```
## Result.isOk (Ok 5)
## ```
@ -16,7 +16,7 @@ isOk = \result ->
Ok _ -> Bool.true
Err _ -> Bool.false
## Return `Bool.true` if the result indicates a failure, else return `Bool.false`
## Returns `Bool.true` if the result indicates a failure, else returns `Bool.false`
## ```
## Result.isErr (Err "uh oh")
## ```
@ -26,7 +26,7 @@ isErr = \result ->
Ok _ -> Bool.false
Err _ -> Bool.true
## If the result is `Ok`, return the value it holds. Otherwise, return
## If the result is `Ok`, returns the value it holds. Otherwise, returns
## the given default value.
## ```
## Result.withDefault (Ok 7) 42
@ -38,8 +38,8 @@ withDefault = \result, default ->
Ok value -> value
Err _ -> default
## If the result is `Ok`, transform the value it holds by running a conversion
## function on it. Then return a new `Ok` holding the transformed value. If the
## 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`.
## ```
## Result.map (Ok 12) Num.negate
@ -54,8 +54,8 @@ map = \result, transform ->
Ok v -> Ok (transform v)
Err e -> Err e
## If the result is `Err`, transform the value it holds by running a conversion
## function on it. Then return a new `Err` holding the transformed value. If
## 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`.
## ```
## Result.mapErr (Err "yipes!") Str.isEmpty
@ -67,8 +67,8 @@ mapErr = \result, transform ->
Ok v -> Ok v
Err e -> Err (transform e)
## If the result is `Ok`, transform the entire result by running a conversion
## function on the value the `Ok` holds. Then return that new result. If the
## 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`.
## ```
## Result.try (Ok -1) \num -> if num < 0 then Err "negative!" else Ok -num
@ -80,8 +80,8 @@ try = \result, transform ->
Ok v -> transform v
Err e -> Err e
## If the result is `Err`, transform the entire result by running a conversion
## function on the value the `Err` holds. Then return that new result. If the
## 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`.
## ```
## Result.onErr (Ok 10) \errorNum -> Str.toNat errorNum