Update docs

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<Text, Nat>;
   } = {
-    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<Text>;
   } = {
-    set = Set.fromIter(TrieSet.toArray(state.set).vals(), Text.compare);
+    set = Set.fromIter(TrieSet.toArray(state.set).values(), Text.compare);
   }
 )
 persistent actorApp {

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,15 +482,15 @@ 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`
 ``` motoko no-repl
 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`.

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<Nat>([0, 1, 2]), List.fromArray<Nat>([2, 3]), List.fromArray<Nat>([]), List.fromArray<Nat>([4])];
-let joinedList = List.join<Nat>(lists.vals());
+let joinedList = List.join<Nat>(lists.values());
 assert List.equal<Nat>(joinedList, List.fromArray<Nat>([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<Nat>([1, 2, 3, 4]);
-let newList = List.flatMap<Nat, Int>(list, func x = [x, -x].vals());
+let newList = List.flatMap<Nat, Int>(list, func x = [x, -x].values());
 assert List.equal(newList, List.fromArray<Int>([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<Nat>(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<Nat>();
 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<Nat>(2, 1);
 
 List.addAll<Nat>(list, iter);

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);

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<Nat, Int>(array, func x = [x, -x].vals());
+let newArray = VarArray.flatMap<Nat, Int>(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<Nat>(arrays.vals());
+let joinedArray = VarArray.join<Nat>(arrays.values());
 assert VarArray.equal(joinedArray, [var 0, 1, 2, 2, 3, 4], Nat.equal);
 ```
 

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<T>(self : List<T>, 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<T>(self : List<T>, 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();
 

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 {
 

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, "");
   };
 };
 ```

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<Nat, Text>(arr, Nat.toText).values())
+  Text.join(Array.map<Nat, Text>(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<Text, Nat> {
-    let map = HashMap.HashMap<Text, Nat>(arr.size(), Text.equal, Text.hash);
-      for ((key, value) in arr.vals()) {
-          map.put(key, value)
-      };
-      map
+  func arrayToMap(arr : [(Text, Nat)]) : Map.Map<Text, Nat> {
+    let map = Map.empty<Text, Nat>();
+    for ((key, value) in arr.values()) {
+      Map.add(map, Text.compare, key, value);
+    };
+    map
   }
 };