Merge branch 'nightly' into b64decode-validation

docs/changelog.md

@@ -34,14 +34,91 @@ what we publish.
   `ExplicitlyCopyable` trait. This will ease the transition to explicit
   copyablility requirements by default in the Mojo collection types.
 
+- Indexing into a homogenous tuple now produces the consistent element type
+  without needing a rebind:
+
+  ```mojo
+    var x = (1, 2, 3, 3, 4)
+    var y : Int = x[idx]     # Just works!
+  ```
+
+- You can now overload positional arguments with a keyword-only argument, and
+  keyword-only arguments with different names:
+
+  ```mojo
+    struct OverloadedKwArgs:
+        var val: Int
+
+        fn __init__(out self, single: Int):
+            self.val = single
+
+        fn __init__(out self, *, double: Int):
+            self.val = double * 2
+
+        fn __init__(out self, *, triple: Int):
+            self.val = triple * 3
+
+        fn main():
+            OverloadedKwArgs(1)        # val=1
+            OverloadedKwArgs(double=1) # val=2
+            OverloadedKwArgs(triple=2) # val=3
+  ```
+
+  This also works with indexing operations:
+
+  ```mojo
+  struct OverloadedKwArgs:
+    var vals: List[Int]
+
+    fn __init__(out self):
+        self.vals = List[Int](0, 1, 2)
+
+    fn __getitem__(self, idx: Int) -> Int:
+        return self.vals[idx]
+
+    fn __getitem__(self, *, idx2: Int) -> Int:
+        return self.vals[idx2 * 2]
+
+    fn __setitem__(mut self, idx: Int, val: Int):
+        self.vals[idx] = val
+
+    fn __setitem__(mut self, val: Int, *, idx2: Int):
+          self.vals[idx2 * 2] = val
+
+
+  fn main():
+      var x = OverloadedKwArgs()
+      print(x[1])       # 1
+      print(x[idx2=1])  # 2
+
+      x[1] = 42
+      x[idx2=1] = 84
+
+      print(x[1])       # 42
+      print(x[idx2=1])  # 84
+  ```
+
 ### Standard library changes
 
 - Add a new `validate` parameter to the `b64decode()` function.
 
-- The `int` function to construct an `Int` has been removed, this was a
-  temporary workaround when Mojo didn't have a way to distinguish between
-  implicit and explicit constructors. You can do a search and replace for `int(`
-  to `Int(` to update your programs.
+- The free floating functions for constructing different types have been
+  deprecated for actual constructors:
+
+  ```plaintext
+  before   after
+  ------------------
+  int()    Int()
+  str()    String()
+  bool()   Bool()
+  float()  Float64()
+  ```
+
+  These functions were a workaround before Mojo had a way to distinguish between
+  implicit and explicit constructors. For this release you'll get a deprecation
+  warning, and in the next release they'll become compiler errors. You can
+  quickly update your code by doing a `Match Case` and `Match Whole Word`
+  search and replace for `int(` to `Int(` etc.
 
 - `UnsafePointer`'s `bitcast` method has now been split into `bitcast`
   for changing the type, `origin_cast` for changing mutability,
@@ -101,11 +178,26 @@ what we publish.
   functionality.
 
 - Added `Char`, for representing and storing single Unicode characters.
+  - `Char` implements `CollectionElement`, `EqualityComparable`, `Intable`, and
+    `Stringable`.
+  - Added `String` constructor from `Char`
+  - `Char` can be converted to `UInt32` via `Char.to_u32()`.
+  - `Char` provides methods for categorizing character types, including:
+    `Char.is_ascii()`, `Char.is_posix_space()`, `Char.is_python_space()`,
+    `Char.is_ascii_digit()`, `Char.is_ascii_upper()`, `Char.is_ascii_lower()`,
+    `Char.is_ascii_printable()`.
+
+- `chr(Int)` will now abort if given a codepoint value that is not a valid
+  `Char`.
 
 - Added `StringSlice.from_utf()` factor method, for validated construction of
   a `StringSlice` from a buffer containing UTF-8 encoded data. This method will
   raise if the buffer contents are not valid UTF-8.
 
+- Added `StringSlice.chars()` which returns an iterator over `Char`s. This is a
+  compliant UTF-8 decoder that returns each Unicode codepoint encoded in the
+  string.
+
 - Several standard library functions have been changed to take `StringSlice`
   instead of `String`. This generalizes them to be used for any appropriately
   encoded string in memory, without requiring that the string be heap allocated.
@@ -122,6 +214,43 @@ what we publish.
   - `b16encode()`
   - `b16decode()`
 
+- Added new `String.chars()` and `String.char_slices()` iterator methods, and
+  deprecated the existing `String.__iter__()` method.
+
+  Different use-cases may prefer iterating over the `Char`s encoded in a string,
+  or iterating over subslices containing single characters. Neither iteration
+  semantics is an obvious default, so the existing `__iter__()` method has been
+  deprecated in favor of writing explicit iteration methods for the time being.
+
+  Code of the form:
+
+  ```mojo
+  var s: String  = ...
+  for c in s:
+      # ...
+  ```
+
+  can be migrated to using the `.char_slices()` method:
+
+  ```mojo
+  var s: String = ...
+  for c in s.char_slices():
+      # ...
+  ```
+
+- The `String.__len__()` and `StringSlice.__len__()` methods now return the
+  length of the string in bytes.
+
+  Previously, these methods were documented to note that they would eventually
+  return a length in Unicode codepoints. They have been changed to guarantee
+  a length in bytes, since the length in bytes is how they are most often used
+  today (for example, as bounds to low-level memory manipulation logic).
+  Additionally, length in codepoints is a more specialized notion of string
+  length that is rarely the correct metric.
+
+  Users that know they need the length in codepoints can use the
+  `str.char_length()` method, or `len(str.chars())`.
+
 - Various functionality has moved from `String` and `StringRef` to the more
   general `StringSlice` type.
 
@@ -136,6 +265,15 @@ what we publish.
   has narrower comparison methods that support comparing only with
   `StringSlice`'s with the exact same origin.
 
+- Added `StringSlice.char_length()` method, to pair with the existing
+  `StringSlice.byte_length()` method.
+
+  In a future version of Mojo, `StringSlice.__len__()` may be changed to return
+  the length in bytes, matching the convention of string length methods in
+  languages like C++ and Rust. Callers that know they need the length in
+  Unicode codepoints should update to calling `StringSlice.char_length()`
+  instead.
+
 - Removed `@implicit` decorator from some standard library initializer methods
   that perform allocation. This reduces places where Mojo code could implicitly
   allocate where the user may not be aware.
@@ -175,6 +313,62 @@ what we publish.
           return self.i
   ```
 
+- You can now cast SIMD types using constructors:
+
+  ```mojo
+  var val = Int8(42)
+  var cast = Int32(val)
+  ```
+
+  It also works when passing a scalar type to larger vector size:
+
+  ```mojo
+  var vector = SIMD[DType.int64, 4](cast) # [42, 42, 42, 42]
+  ```
+
+  For values other than scalars the size of the SIMD vector needs to be equal:
+
+  ```mojo
+  var float_vector = SIMD[DType.float64, 4](vector)
+  ```
+
+  `SIMD.cast` still exists to infer the size of new vector:
+
+  ```mojo
+  var inferred_size = float_vector.cast[DType.uint64]() # [42, 42, 42, 42]
+  ```
+
+- You can now use `max()` and `min()` with variadic number of arguments.
+
+- A new `LinkedList` type has been added to the standard library.
+
+- The `String.write` static method has moved to a `String` constructor, and
+  is now buffered. Instead of doing:
+
+  ```mojo
+  var msg = "my message " + String(x) + " " + String(y) + " " + String(z)
+  ```
+
+  Which reallocates the `String` you should do:
+
+  ```mojo
+  var msg = String("my message", x, y, z, sep=" ")
+  ```
+
+  Which is cleaner, and buffers to the stack so the `String` is allocated only
+  once.
+
+- You can now pass any `Writer` to `write_buffered`:
+
+  ```mojo
+  from utils.write import write_buffered
+
+  var string = String("existing string")
+  write_buffered(string, 42, 42.4, True, sep=" ")
+  ```
+
+  This writes to a buffer on the stack before reallocating the `String`.
+
 ### Tooling changes
 
 - mblack (aka `mojo format`) no longer formats non-mojo files. This prevents
@@ -191,6 +385,8 @@ what we publish.
   - Added `Path` explicit constructor from `StringSlice`.
   - removed `StringRef.startswith()` and `StringRef.endswith()`
   - removed `StringRef.strip()`
+- The `Tuple.get[i, T]()` method has been removed. Please use `tup[i]` or
+  `rebind[T](tup[i])` as needed instead.
 
 ### 🛠️ Fixed
 
@@ -199,14 +395,17 @@ what we publish.
 - The command `mojo debug --vscode` now sets the current working directory
   properly.
 
-- [Issue #3796](https://github.com/modularml/mojo/issues/3796) - Compiler crash
+- [Issue #3796](https://github.com/modular/mojo/issues/3796) - Compiler crash
   handling for-else statement.
 
-- [Issue #3540](https://github.com/modularml/mojo/issues/3540) - Using named
+- [Issue #3540](https://github.com/modular/mojo/issues/3540) - Using named
   output slot breaks trait conformance
 
-- [Issue #3617](https://github.com/modularml/mojo/issues/3617) - Can't generate
+- [Issue #3617](https://github.com/modular/mojo/issues/3617) - Can't generate
   the constructors for a type wrapping `!lit.ref`
 
 - The Mojo Language Server doesn't crash anymore on empty **init**.mojo files.
-  [Issue #3826](https://github.com/modularml/mojo/issues/3826).
+  [Issue #3826](https://github.com/modular/mojo/issues/3826).
+
+- [Issue #3935](https://github.com/modular/mojo/issues/3935) - Confusing OOM
+   error when using Tuple.get incorrectly.

docs/faq.md

@@ -147,7 +147,7 @@ develop AI algorithms, but as we grow Mojo into a superset of Python, you can
 use it for other things like HPC, data transformations, writing pre/post
 processing operations, and much more. For examples of how Mojo can be used for
 other general programming tasks, see our [Mojo
-examples](https://github.com/modularml/mojo/tree/main/examples).
+examples](https://github.com/modular/mojo/tree/main/examples).
 
 ### Is Mojo interpreted or compiled?
 
@@ -245,7 +245,7 @@ multiplication](https://www.modular.com/blog/the-worlds-fastest-unified-matrix-m
 ### Mojo’s matmul performance in the notebook doesn’t seem that great. What’s going on?
 
 The [Mojo Matmul
-notebook](https://github.com/modularml/mojo/blob/main/examples/notebooks/Matmul.ipynb)
+notebook](https://github.com/modular/mojo/blob/main/examples/notebooks/Matmul.ipynb)
 uses matrix multiplication to show off some Mojo features in a scenario that
 you would never attempt in pure Python. So that implementation is like a “toy”
 matmul implementation and it doesn’t measure up to the state of the art.
@@ -270,8 +270,8 @@ dashboard](https://www.modular.com/max/performance).
 
 ### How can I get access to the SDK?
 
-Mojo is included with the MAX SDK, which you can [download and use for
-free](/max/install).
+Mojo is included with the `max` conda package. Try it now by following
+the tutorial to [get started with Mojo](/mojo/manual/get-started).
 
 Read more about [why Mojo is bundled with
 MAX](/max/faq#why-bundle-mojo-with-max).
@@ -282,7 +282,7 @@ Yes, but it's different. When we first announced Mojo, it was available
 only through login, in a JupyterLab environment. Now that Mojo is available
 for local development, we've shut down that service (you can instead [run
 Mojo notebooks
-locally](https://github.com/modularml/mojo/tree/main/examples/notebooks#readme)).
+locally](https://github.com/modular/mojo/tree/main/examples/notebooks#readme)).
 
 The new [Mojo Playground](/mojo/playground) is built into the docs website
 and does not require login.
@@ -301,7 +301,7 @@ and does not require login.
   using buttons in the Playground toolbar.
 
 - There might be some bugs. Please [report issues and feedback on
-  GitHub](https://github.com/modularml/mojo/issues/new/choose).
+  GitHub](https://github.com/modular/mojo/issues/new/choose).
 
 ### What are the license terms for the SDK?
 

docs/manual/basics.mdx

@@ -77,7 +77,7 @@ def main():
 You don't need a `main()` function when coding in the
 [REPL](/mojo/manual/get-started#2-run-code-in-the-repl) or in a
 [Jupyter
-notebook](https://github.com/modularml/mojo/tree/main/examples/notebooks#readme).
+notebook](https://github.com/modular/mojo/tree/main/examples/notebooks#readme).
 
 :::
 
@@ -390,14 +390,14 @@ here is [Functions](/mojo/manual/functions).
 Otherwise, here are some other resources to check out:
 
 * If you want to experiment with some code, clone [the Mojo
-  repo](https://github.com/modularml/mojo/) to try our code examples:
+  repo](https://github.com/modular/mojo/) to try our code examples:
 
   ```sh
-  git clone https://github.com/modularml/mojo.git
+  git clone https://github.com/modular/mojo.git
   ```
 
   In addition to several `.mojo` examples, the repo includes [Jupyter
-  notebooks](https://github.com/modularml/mojo/tree/main/examples/notebooks#readme)
+  notebooks](https://github.com/modular/mojo/tree/main/examples/notebooks#readme)
   that teach advanced Mojo features.
 
 * To see all the available Mojo APIs, check out the [Mojo standard library

docs/manual/errors.mdx

@@ -103,12 +103,12 @@ recovery that's appropriate for your application.
 
 If you provide the name of a variable after the `except` keyword, then the
 `Error` instance is bound to the variable if an error occurs. The `Error` type
-implements the [`Writable`](/mojo/stdlib/utils/write/Writable) trait, so
-you can pass it as an argument to the [`print()`](/mojo/stdlib/builtin/io/print)
+implements the [`Writable`](/mojo/stdlib/utils/write/Writable) trait, so you can
+pass it as an argument to the [`print()`](/mojo/stdlib/builtin/io/print)
 function if you'd like to print its error message to the console. It also
 implements the [`Stringable`](/mojo/stdlib/builtin/str/Stringable) trait, so you
-can pass it to the [`str()`](/mojo/stdlib/builtin/str/str) function if you want
-to extract the error message as a `String` for further processing.
+can construct a `String` with `String(error)` if you want to extract the error
+message as a `String` for further processing.
 
 If desired, you can re-raise an error condition from your `except` clause simply
 by executing a `raise` statement from within its code block. This can be either
@@ -152,7 +152,7 @@ def main():
             print("try     =>", value[])
             if value[] == 1:
                 continue
-            result = str("{} incremented is {}").format(value[], incr(value[]))
+            result = String("{} incremented is {}").format(value[], incr(value[]))
         except e:
             print("except  =>", e)
         else:
@@ -384,7 +384,7 @@ struct ConditionalTimer:
         print("Elapsed time:", elapsed_time_ms, "milliseconds")
 
     fn __exit__(mut self, e: Error) raises -> Bool:
-        if str(e) == "just a warning":
+        if String(e) == "just a warning":
             print("Suppressing error:", e)
             self.__exit__()
             return True