From ae727dab0cc2153452c4dd0e8448ee433cb2c7eb Mon Sep 17 00:00:00 2001 From: Andri Schatz Date: Thu, 19 Feb 2026 11:19:50 +0100 Subject: [PATCH] refactor: update function calls to use 'values()' instead of 'vals()' for consistency across documentation This change improves clarity and aligns with the updated API conventions in the core library. Adjustments made in multiple files including character text handling, type conversions, and various core data structures. --- doc/md/12-base-core-migration.md | 30 +++++++++++++++--- doc/md/core/Float.md | 6 ++-- doc/md/core/List.md | 10 +++--- doc/md/core/Set.md | 2 +- doc/md/core/VarArray.md | 4 +-- doc/md/core/pure/List.md | 31 +++++++++++++++++-- doc/md/examples/StableLog.mo | 3 +- .../1-basic-syntax/5-characters-text.md | 2 +- .../3-types/15-type-conversions.md | 16 +++++----- 9 files changed, 75 insertions(+), 29 deletions(-) diff --git a/doc/md/12-base-core-migration.md b/doc/md/12-base-core-migration.md index cc36143e029..a53182a9d89 100644 --- a/doc/md/12-base-core-migration.md +++ b/doc/md/12-base-core-migration.md @@ -126,7 +126,7 @@ The `core` package brings significant changes to data structures, making a clear - `append()` → `concat()` - `chain()` → `flatMap()` - `freeze()` → `fromVarArray()` -- `init()` → `repeat()` with reversed argument order +- `init(n, f)` (mutable, from generator) → use `VarArray.tabulate(n, f)` for mutable arrays; for a repeated value use `Array.repeat(value, n)` (reversed argument order from base). - `make()` → `singleton()` - `mapFilter()` → `filterMap()` - `slice()` → `range()` @@ -201,6 +201,9 @@ The `core` package brings significant changes to data structures, making a clear - `equal()` - Now requires epsilon parameter - `notEqual()` - Now requires epsilon parameter +#### Parameter order changes +- `format(fmt, x)` → `format(x, fmt)` or `x.format(fmt)` (value first, then format) + #### Removed functions - `equalWithin()`, `notEqualWithin()` - Use `equal()` and `notEqual()` with epsilon @@ -209,8 +212,8 @@ The `core` package brings significant changes to data structures, making a clear `Iter.range()` has been removed in favor of type-specific range functions such as `Nat.range()`, `Int.range()`, `Nat32.range()`, etc. These functions have an **exclusive upper bound**, in contrast to the original inclusive upper bound of `Iter.range()`. ```motoko no-repl -import Int "mo:base/Int"; -import Debug "mo:base/Debug"; +import Int "mo:core/Int"; +import Debug "mo:core/Debug"; persistent actor { // Iterate through -3, -2, -1, 0, 1, 2 (exclusive upper bound) @@ -265,6 +268,9 @@ Helper functions have been added, such as `allValues()`, for each finite type in - `maximumValue` → `maxValue` - `minimumValue` → `minValue` +#### Breaking changes +- `fromInt32(self, x)` → `fromInt32(x)` (no `self` parameter in `Int8`, `Int16`, `Int64`) + #### New functions - `allValues()` - Iterator over all values in range - `range()`, `rangeInclusive()` - Range iterators (replaces `Iter.range()`) @@ -284,6 +290,17 @@ Helper functions have been added, such as `allValues()`, for each finite type in - `assertNull()` - Removed in favor of pattern matching - `assertSome()` - Removed in favor of pattern matching +### [`pure/List`](./core/pure/List) + +#### Renamed functions +- `get()` → `at()` - Indexed access; traps if out of bounds +- `getOpt()` → `get()` - Optional indexed access (returns `?T`) + +### [`Map`](./core/Map) + +#### Renamed functions +- `replaceIfExists()` → `replace()` - Replace value for an existing key; returns previous value or `null` + ### [`Order`](./core/Order) #### New functions @@ -339,6 +356,9 @@ persistent actor { ### [`Text`](./core/Text) +#### Parameter order changes +- `join(sep, iter)` → `join(iter, sep)` (iterator first, then separator) + #### Renamed functions - `toLowercase()` → `toLower()` - `toUppercase()` → `toUpper()` @@ -583,7 +603,7 @@ import Iter "mo:core/Iter"; ) : { map : Map.Map; } = { - map = Map.fromIter(state.mapEntries.vals(), Text.compare); + map = Map.fromIter(state.mapEntries.values(), Text.compare); } ) persistent actor{ @@ -927,7 +947,7 @@ import TrieSet "mo:base/TrieSet"; ) : { set : Set.Set; } = { - set = Set.fromIter(TrieSet.toArray(state.set).vals(), Text.compare); + set = Set.fromIter(TrieSet.toArray(state.set).values(), Text.compare); } ) persistent actorApp { diff --git a/doc/md/core/Float.md b/doc/md/core/Float.md index dbef6517900..8dd2ada4f90 100644 --- a/doc/md/core/Float.md +++ b/doc/md/core/Float.md @@ -464,7 +464,7 @@ assert Float.equal(Float.log(Float.e), 1.0, epsilon); func format(self : Float, fmt : {#fix : Nat8; #exp : Nat8; #gen : Nat8; #exact}) : Text ``` -Formatting. `format(fmt, x)` formats `x` to `Text` according to the +Formatting. `format(self, fmt)` (or `x.format(fmt)`) formats the float to `Text` according to the formatting directive `fmt`, which can take one of the following forms: * `#fix prec` as fixed-point format with `prec` digits @@ -482,7 +482,7 @@ differently, i.e. "NaN" or "nan", potentially omitting the `NaN` sign. Example: ```motoko include=import no-validate -assert Float.format(#exp 3, 123.0) == "1.230e+02"; +assert Float.format(123.0, #exp 3) == "1.230e+02"; ``` ## Function `toText` @@ -490,7 +490,7 @@ assert Float.format(#exp 3, 123.0) == "1.230e+02"; func toText(self : Float) : Text ``` -Conversion to Text. Use `format(fmt, x)` for more detailed control. +Conversion to Text. Use `format(self, fmt)` or `x.format(fmt)` for more detailed control. `-0.0` is formatted with negative sign bit. Positive infinity is formatted as `inf`. diff --git a/doc/md/core/List.md b/doc/md/core/List.md index 88dae98494b..09e266e0bfe 100644 --- a/doc/md/core/List.md +++ b/doc/md/core/List.md @@ -244,7 +244,7 @@ Consider using `List.flatten()` for better performance. import Nat "mo:core/Nat"; let lists = [List.fromArray([0, 1, 2]), List.fromArray([2, 3]), List.fromArray([]), List.fromArray([4])]; -let joinedList = List.join(lists.vals()); +let joinedList = List.join(lists.values()); assert List.equal(joinedList, List.fromArray([0, 1, 2, 2, 3, 4]), Nat.equal); ``` @@ -436,7 +436,7 @@ and concatenating the resulting iterators in order. import Int "mo:core/Int" let list = List.fromArray([1, 2, 3, 4]); -let newList = List.flatMap(list, func x = [x, -x].vals()); +let newList = List.flatMap(list, func x = [x, -x].values()); assert List.equal(newList, List.fromArray([1, -1, 2, -2, 3, -3, 4, -4]), Int.equal); ``` Runtime: O(size) @@ -1033,7 +1033,7 @@ import Nat "mo:core/Nat"; import Iter "mo:core/Iter"; let array = [1, 1, 1]; -let iter = array.vals(); +let iter = array.values(); let list = List.fromIter(iter); assert Iter.toArray(List.values(list)) == [1, 1, 1]; @@ -1055,7 +1055,7 @@ import Nat "mo:core/Nat"; import Iter "mo:core/Iter"; let array = [1, 1, 1]; -let iter = array.vals(); +let iter = array.values(); let list = iter.toList(); assert Iter.toArray(List.values(list)) == [1, 1, 1]; @@ -1095,7 +1095,7 @@ import Nat "mo:core/Nat"; import Iter "mo:core/Iter"; let array = [1, 1, 1]; -let iter = array.vals(); +let iter = array.values(); let list = List.repeat(2, 1); List.addAll(list, iter); diff --git a/doc/md/core/Set.md b/doc/md/core/Set.md index 57ab55141a0..c2a30791396 100644 --- a/doc/md/core/Set.md +++ b/doc/md/core/Set.md @@ -9,7 +9,7 @@ import Set "mo:core/Set"; import Nat "mo:core/Nat"; persistent actor { - let set = Set.fromIter([3, 1, 2, 3].vals(), Nat.compare); + let set = Set.fromIter([3, 1, 2, 3].values(), Nat.compare); assert Set.size(set) == 3; assert not Set.contains(set, Nat.compare, 4); let diff = Set.difference(set, set, Nat.compare); diff --git a/doc/md/core/VarArray.md b/doc/md/core/VarArray.md index 1e48a27a320..88a9ec4af39 100644 --- a/doc/md/core/VarArray.md +++ b/doc/md/core/VarArray.md @@ -430,7 +430,7 @@ and concatenating the resulting arrays in order. import Int "mo:core/Int" let array = [var 1, 2, 3, 4]; -let newArray = VarArray.flatMap(array, func x = [x, -x].vals()); +let newArray = VarArray.flatMap(array, func x = [x, -x].values()); assert VarArray.equal(newArray, [var 1, -1, 2, -2, 3, -3, 4, -4], Int.equal); ``` Runtime: O(size) @@ -503,7 +503,7 @@ Consider using `VarArray.flatten()` for better performance. import Nat "mo:core/Nat"; let arrays : [[var Nat]] = [[var 0, 1, 2], [var 2, 3], [var], [var 4]]; -let joinedArray = VarArray.join(arrays.vals()); +let joinedArray = VarArray.join(arrays.values()); assert VarArray.equal(joinedArray, [var 0, 1, 2, 2, 3, 4], Nat.equal); ``` diff --git a/doc/md/core/pure/List.md b/doc/md/core/pure/List.md index 95f9bb2d551..2bc132e085c 100644 --- a/doc/md/core/pure/List.md +++ b/doc/md/core/pure/List.md @@ -103,12 +103,37 @@ Space: O(1) *Runtime and space assumes that `equal` runs in O(1) time and space. +## Function `at` +``` motoko no-repl +func at(self : List, n : Nat) : T +``` + +Access any item in a list by index (zero-based). Traps if the index is out of bounds. + +NOTE: Indexing into a list is a linear operation, and usually an +indication that a list might not be the best data structure +to use. + +Example: +```motoko +import List "mo:core/pure/List"; + +persistent actor { + let list = ?(0, ?(1, null)); + assert List.at(list, 1) == 1; +} +``` + +Runtime: O(size) + +Space: O(1) + ## Function `get` ``` motoko no-repl func get(self : List, n : Nat) : ?T ``` -Access any item in a list, zero-based. +Optional access to any item in a list by index (zero-based). Returns `null` if the index is out of bounds. NOTE: Indexing into a list is a linear operation, and usually an indication that a list might not be the best data structure @@ -1017,7 +1042,7 @@ Example: import List "mo:core/pure/List"; persistent actor { - let list = List.fromIter([0, 1, 2, 3, 4].vals()); + let list = List.fromIter([0, 1, 2, 3, 4].values()); assert list == ?(0, ?(1, ?(2, ?(3, ?(4, null))))); } ``` @@ -1037,7 +1062,7 @@ Example: import List "mo:core/pure/List"; persistent actor { - transient let iter = [0, 1, 2, 3, 4].vals(); + transient let iter = [0, 1, 2, 3, 4].values(); let list = iter.toList(); diff --git a/doc/md/examples/StableLog.mo b/doc/md/examples/StableLog.mo index f930b832389..a688b0a5240 100644 --- a/doc/md/examples/StableLog.mo +++ b/doc/md/examples/StableLog.mo @@ -4,7 +4,8 @@ import Text "mo:core/Text"; import Array "mo:core/Array"; import VarArray "mo:core/VarArray"; -import StableMemory "mo:base/ExperimentalStableMemory"; // deprecated +// Low-level stable memory: core has no direct replacement; base ExperimentalStableMemory is deprecated but still used here for this example. +import StableMemory "mo:base/ExperimentalStableMemory"; persistent actor StableLog { diff --git a/doc/md/fundamentals/1-basic-syntax/5-characters-text.md b/doc/md/fundamentals/1-basic-syntax/5-characters-text.md index d907a59c559..587cab8626c 100644 --- a/doc/md/fundamentals/1-basic-syntax/5-characters-text.md +++ b/doc/md/fundamentals/1-basic-syntax/5-characters-text.md @@ -65,7 +65,7 @@ persistent actor Alternator { transformedText; }); - return Text.join("", modified); + return Text.join(modified, ""); }; }; ``` diff --git a/doc/md/fundamentals/3-types/15-type-conversions.md b/doc/md/fundamentals/3-types/15-type-conversions.md index 569ef92a6c8..632333dbcf5 100644 --- a/doc/md/fundamentals/3-types/15-type-conversions.md +++ b/doc/md/fundamentals/3-types/15-type-conversions.md @@ -154,7 +154,7 @@ import Array "mo:core/Array"; import Nat "mo:core/Nat"; func arrayOfNatToText(arr : [Nat]) : Text { - Text.join(" ", Array.map(arr, Nat.toText).values()) + Text.join(Array.map(arr, Nat.toText).values(), " ") }; assert arrayOfNatToText([1, 2, 3]) == "1 2 3"; @@ -165,16 +165,16 @@ assert arrayOfNatToText([1, 2, 3]) == "1 2 3"; Motoko lacks support for dynamic objects, so an array of tuples is converted into a [record](../3-types/5-records.md) or a structured representation. ```motoko no-repl -import HashMap "mo:core/HashMap"; +import Map "mo:core/Map"; import Text "mo:core/Text"; persistent actor MapConverter { - func arrayToMap(arr : [(Text, Nat)]) : HashMap.HashMap { - let map = HashMap.HashMap(arr.size(), Text.equal, Text.hash); - for ((key, value) in arr.vals()) { - map.put(key, value) - }; - map + func arrayToMap(arr : [(Text, Nat)]) : Map.Map { + let map = Map.empty(); + for ((key, value) in arr.values()) { + Map.add(map, Text.compare, key, value); + }; + map } };