From b8b0137504d388efbe2d1ba5082c0dcabcd8bc8a Mon Sep 17 00:00:00 2001
From: Laurenz <laurmaedje@gmail.com>
Date: Fri, 4 Aug 2023 15:09:01 +0200
Subject: Bytes type

- Moves `Bytes` from `util` to `eval` module
- Accepts bytes in `str` function for bytes -> str conversion
- Adds `bytes` function for str | array -> bytes conversion
- Adds `array` function for bytes -> array conversion
- Adds `len`, `at`, and `slice` methods for bytes
- Adds `encoding` parameter to `read` function
---
 docs/reference/types.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 70 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/reference/types.md b/docs/reference/types.md
index d7cfaa65..62c59cb0 100644
--- a/docs/reference/types.md
+++ b/docs/reference/types.md
@@ -46,6 +46,8 @@ integers, integers cannot be smaller than `{-9223372036854775808}` or larger tha
 The number can also be specified as hexadecimal, octal, or binary by starting it
 with a zero followed by either `x`, `o`, or `b`.
 
+You can convert a value to an integer with the [`float`]($func/float) function.
+
 ## Example
 ```example
 #(1 + 2) \
@@ -64,6 +66,8 @@ A limited-precision representation of a real number. Typst uses 64 bits to
 store floats. Wherever a float is expected, you can also pass an
 [integer]($type/integer).
 
+You can convert a value to a float with the [`float`]($func/float) function.
+
 ## Example
 ```example
 #3.14 \
@@ -87,6 +91,8 @@ A length has the following fields:
 - `abs`: A length with just the absolute component of the current length
 (that is, excluding the `em` component).
 
+You can multiply lengths with and divide them by integers and floats.
+
 ## Example
 ```example
 #rect(width: 20pt)
@@ -458,6 +464,65 @@ $arrow.r$ \
 $arrow.t.quad$
 ```
 
+# Bytes
+A sequence of bytes.
+
+This is conceptually similar to an array of [integers]($type/integer) between
+`{0}` and `{255}`, but represented much more efficiently.
+
+You can convert
+- a [string]($type/string) or an [array]($type/array) of integers to bytes with
+  the [`bytes`]($func/bytes) function
+- bytes to a string with the [`str`]($func/str) function
+- bytes to an array of integers with the [`array`]($func/array) function
+
+When [reading]($func/read) data from a file, you can decide whether to load it
+as a string or as raw bytes.
+
+```example
+#bytes((123, 160, 22, 0)) \
+#bytes("Hello 😃")
+
+#let data = read(
+  "rhino.png",
+  encoding: none,
+)
+
+// Magic bytes.
+#array(data.slice(0, 4)) \
+#str(data.slice(1, 4))
+```
+
+## Methods
+### len()
+The length in bytes.
+
+- returns: integer
+
+### at()
+Returns the byte at the specified index. Returns the default value if the index
+is out of bounds or fails with an error if no default value was specified.
+
+- index: integer (positional, required)
+  The index at which to retrieve the byte.
+- default: any (named)
+  A default value to return if the index is out of bounds.
+- returns: integer or any
+
+### slice()
+Extract a subslice of the bytes.
+Fails with an error if the start or index is out of bounds.
+
+- start: integer (positional, required)
+  The start index (inclusive).
+- end: integer (positional)
+  The end index (exclusive). If omitted, the whole slice until the end is
+  extracted.
+- count: integer (named)
+  The number of bytes to extract. This is equivalent to passing
+  `start + count` as the `end` position. Mutually exclusive with `end`.
+- returns: bytes
+
 # String
 A sequence of Unicode codepoints.
 
@@ -475,6 +540,8 @@ quite versatile.
 All lengths and indices are expressed in terms of UTF-8 characters. Indices are
 zero-based and negative indices wrap around to the end of the string.
 
+You can convert a value to a string with the [`str`]($func/str) function.
+
 ### Example
 ```example
 #"hello world!" \
@@ -521,7 +588,7 @@ value was specified.
   The byte index.
 - default: any (named)
   A default value to return if the index is out of bounds.
-- returns: string
+- returns: string or any
 
 ### slice()
 Extract a substring of the string.
@@ -839,8 +906,8 @@ Fails with an error if the start or index is out of bounds.
   The end index (exclusive). If omitted, the whole slice until the end of the
   array is extracted.
 - count: integer (named)
-  The number of items to extract. This is equivalent to passing `start +
-  count` as the `end` position. Mutually exclusive with `end`.
+  The number of items to extract. This is equivalent to passing
+  `start + count` as the `end` position. Mutually exclusive with `end`.
 - returns: array
 
 ### contains()
-- 
cgit v1.2.3