Merge remote-tracking branch 'upstream/nightly' into make-list-size-p…

…rivate

docs/changelog-released.md

@@ -60,7 +60,7 @@ detailed information in the following sections:
   [`UnsafePointer`](/mojo/stdlib/memory/unsafe_pointer/UnsafePointer) instead.
   Functions that previously took a `DTypePointer` now take an equivalent
   `UnsafePointer`. For more information on using pointers, see [Unsafe
-  pointers](/mojo/manual/pointers) in the Mojo Manual.
+  pointers](/mojo/manual/pointers/unsafe-pointers) in the Mojo Manual.
 
 - There are many new standard library APIs, with new features for strings,
   collections, and interacting with the filesystem and environment. Changes are
@@ -518,7 +518,7 @@ detailed information in the following sections:
   - `DTypePointer`, `LegacyPointer`, and `Pointer` have been removed. Use
     [`UnsafePointer`](/mojo/stdlib/memory/unsafe_pointer/UnsafePointer) instead.
     For more information on using pointers, see [Unsafe
-    pointers](/mojo/manual/pointers) in the Mojo Manual.
+    pointers](/mojo/manual/pointers/unsafe-pointers) in the Mojo Manual.
 
     Functions that previously took a `DTypePointer` now take an
     equivalent `UnsafePointer`. A quick rule for conversion from `DTypePointer` to
@@ -1013,7 +1013,7 @@ Big themes for this release:
 
 - New Mojo Manual pages on [Control flow](/mojo/manual/control-flow),
   [Testing](/mojo/tools/testing) and using
-  [unsafe pointers](/mojo/manual/pointers).
+  [unsafe pointers](/mojo/manual/pointers/unsafe-pointers).
 
 ### Language changes
 

docs/changelog.md

@@ -288,9 +288,23 @@ what we publish.
   memory allocation and performance. These options allow for optimized memory usage
   and reduced buffer reallocations, providing flexibility based on application requirements.
 
-- A new `StringLiteral.from_string[someString]()` method is available.  It
+- A new `StringLiteral.get[some_stringable]()` method is available.  It
   allows forming a runtime-constant StringLiteral from a compile-time-dynamic
-  `String` value.
+  `Stringable` value.
+
+- `Span` now implements `__reversed__`. This means that one can get a
+  reverse iterator over a `Span` using `reversed(my_span)`. Users should
+  currently prefer this method over `my_span[::-1]`.
+
+- `StringSlice` now implements `strip`, `rstrip`, and `lstrip`.
+
+- Introduced the `@explicit_destroy` annotation, the `__disable_del` keyword,
+  the `UnknownDestructibility` trait, and the `ImplicitlyDestructible` keyword,
+  for the experimental explicitly destroyed types feature.
+
+- Added associated types; we can now have aliases like `alias T: AnyType`,
+  `alias N: Int`, etc. in a trait, and then specify them in structs that conform
+  to that trait.
 
 ### 🦋 Changed
 
@@ -321,6 +335,24 @@ what we publish.
   release of Mojo, but will be removed in the future.  Please migrate to the
   new syntax.
 
+- Similarly, the spelling of "named functions results" has switched to use `out`
+  syntax instead of `-> T as name`.  Functions may have at most one named result
+  or return type specified with the usual `->` syntax.  `out` arguments may
+  occur anywhere in the argument list, but are typically last (except for
+  `__init__` methods, where they are typically first).
+
+  ```mojo
+  # This function has type "fn() -> String"
+  fn example(out result: String):
+    result = "foo"
+  ```
+
+  The parser still accepts the old syntax as a synonym for this, but that will
+  eventually be deprecated and removed.
+
+  This was [discussed extensively in a public
+  proposal](https://github.com/modularml/mojo/issues/3623).
+
 - More things have been removed from the auto-exported set of entities in the `prelude`
   module from the Mojo standard library.
   - `UnsafePointer` has been removed. Please explicitly import it via
@@ -357,7 +389,7 @@ what we publish.
   `String.write`. Here's an example of using all the changes:
 
   ```mojo
-  from utils import Span
+  from memory import Span
 
   @value
   struct NewString(Writer, Writable):
@@ -453,6 +485,19 @@ what we publish.
   for more information and rationale.  As a consequence the `__lifetime_of()`
   operator is now named `__origin_of()`.
 
+- `Origin` is now a complete wrapper around the MLIR origin type.
+
+  - The `Origin.type` alias has been renamed to `_mlir_origin`. In parameter
+    lists, you can now write just `Origin[..]`, instead of `Origin[..].type`.
+
+  - `ImmutableOrigin` and `MutableOrigin` are now, respectively, just aliases
+    for `Origin[False]` and `Origin[True]`.
+
+  - `Origin` struct values are now supported in the brackets of a `ref [..]`
+    argument.
+
+  - Added `Origin.cast_from` for casting the mutability of an origin value.
+
 - You can now use the `+=` and `*` operators on a `StringLiteral` at compile
   time using the `alias` keyword:
 
@@ -566,6 +611,18 @@ what we publish.
   fn take_imm_slice(a: ImmStringSlice): ...
   ```
 
+- Added `PythonObject.__contains__`.
+  ([PR #3101](https://github.com/modularml/mojo/pull/3101) by [@rd4com](https://github.com/rd4com))
+
+  Example usage:
+
+  ```mojo
+  x = PythonObject([1,2,3])
+  if 1 in x:
+     print("1 in x")
+
+- `Span` has moved from the `utils` module to the `memory` module.
+
 ### ❌ Removed
 
 - The `UnsafePointer.bitcast` overload for `DType` has been removed.  Wrap your
@@ -607,6 +664,12 @@ what we publish.
 - [Issue #3815](https://github.com/modularml/mojo/issues/3815) -
   [BUG] Mutability not preserved when taking the union of two origins.
 
+- [Issue #3829](https://github.com/modularml/mojo/issues/3829) - Poor error
+  message when invoking a function pointer upon an argument of the wrong origin
+
+- [Issue #3830](https://github.com/modularml/mojo/issues/3830) - Failures
+  emitting register RValues to ref arguments.
+
 - The VS Code extension now auto-updates its private copy of the MAX SDK.
 
 - The variadic initializer for `SIMD` now works in parameter expressions.

docs/manual/decorators/implicit.md

@@ -0,0 +1,40 @@
+---
+title: '@implicit'
+description: Marks a constructor as eligible for implicit conversion.
+codeTitle: true
+
+---
+
+You can add the `@implicit` decorator on any single-argument constructor to
+identify it as eligible for implicit conversion.
+
+For example:
+
+```mojo
+struct MyInt:
+    var value: Int
+
+    @implicit
+    fn __init__(out self, value: Int):
+        self.value = value
+
+    fn __init__(out self, value: Float64):
+        self.value = int(value)
+
+
+```
+
+This implicit conversion constructor allows you to pass an `Int` to a function
+that takes a `MyInt` argument, or assign an `Int` to a variable of type `MyInt`.
+However, the constructor that takes a `Float64` value is **not** an implicit
+conversion constructor, so it must be invoked explicitly:
+
+```mojo
+fn func(n: MyInt):
+    print("MyInt value: ", n.value)
+
+fn main():
+    func(Int(42))             # Implicit conversion from Int: OK
+    func(MyInt(Float64(4.2))) # Explicit conversion from Float64: OK
+    func(Float64(4.2))        # Error: can't convert Float64 to MyInt
+```

docs/manual/decorators/index.mdx

@@ -9,6 +9,7 @@ listing:
     contents:
       - always-inline.md
       - copy-capture.md
+      - implicit.md
       - nonmaterializable.md
       - parameter.md
       - register-passable.md

docs/manual/index.md

@@ -56,7 +56,8 @@ feedback](https://www.modular.com/community).
 
 - **Pointers**
 
-  - [Unsafe pointers](/mojo/manual/pointers)
+  - [Intro to pointers](/mojo/manual/pointers/)
+  - [Unsafe pointers](/mojo/manual/pointers/unsafe-pointers)
 
 - **Python**
 

docs/manual/lifecycle/life.mdx

@@ -153,12 +153,16 @@ struct MyPet:
 Mojo supports implicit conversion from one type to another. Implicit conversion
 can happen when one of the following occurs:
 
-* You assign a value of one type to a variable with a different type.
-* You pass a value of one type to a function that requires a different type.
+- You assign a value of one type to a variable with a different type.
+- You pass a value of one type to a function that requires a different type.
 
 In both cases, implicit conversion is supported when the target type
-defines a constructor that takes a single required, non-keyword argument of the
-source type. For example:
+defines a constructor that meets the following criteria:
+
+- Is declared with the `@implicit` decorator.
+- Has a single required, non-keyword argument of the source type.
+
+For example:
 
 ```mojo
 var a = Source()
@@ -170,7 +174,9 @@ Mojo implicitly converts the `Source` value in `a` to a `Target` value if
 
 ```mojo
 struct Target:
-  fn __init__(out self, s: Source): ...
+
+    @implicit
+    fn __init__(out self, s: Source): ...
 ```
 
 With implicit conversion, the assignment above is essentially identical to:
@@ -179,26 +185,22 @@ With implicit conversion, the assignment above is essentially identical to:
 var b = Target(a)
 ```
 
+In general, types should only support implicit conversions when the conversion
+lossless, and ideally inexpensive. For example, converting an integer to a
+floating-point number is usually lossless (except for very large positive and
+negative integers, where the conversion may be approximate), but converting a
+floating-point number to an integer is very likely to lose information. So
+Mojo supports implicit conversion from `Int` to `Float64`, but not the reverse.
+
 The constructor used for implicit conversion can take optional arguments, so
 the following constructor would also support implicit conversion from `Source`
 to `Target`:
 
 ```mojo
 struct Target:
-  fn __init__(out self, s: Source, reverse: Bool = False): ...
-```
-
-Implicit conversion also occurs if the type doesn't declare its own constructor,
-but instead uses the [`@value` decorator](#value-decorator), *and* the type
-has only one field. That's because Mojo automatically creates a member-wise
-constructor for each field, and when there is only one field, that synthesized
-constructor works exactly like a conversion constructor. For example, this
-type also can convert a `Source` value to a `Target` value:
 
-```mojo
-@value
-struct Target:
-  var s: Source
+    @implicit
+    fn __init__(out self, s: Source, reverse: Bool = False): ...
 ```
 
 Implicit conversion can fail if Mojo can't unambiguously match the conversion to
@@ -209,41 +211,39 @@ convert the values:
 
 ```mojo
 struct A:
-  fn __init__(out self, s: Source): ...
+    @implicit
+    fn __init__(out self, s: Source): ...
 
 struct B:
-  fn __init__(out self, s: Source): ...
+    @implicit
+    fn __init__(out self, s: Source): ...
 
-struct Target:
-  fn __init__(out self, a: A): ...
-  fn __init__(out self, b: B): ...
+struct OverloadedTarget:
+    @implicit
+    fn __init__(out self, a: A): ...
+    @implicit
+    fn __init__(out self, b: B): ...
 
-# Fails
-var t = Target(Source())
+var t = OverloadedTarget(Source()) # Error: ambiguous call to '__init__': each
+                                   # candidate requires 1 implicit conversion
 ```
 
-In this case, removing either one of the target type's constructors will fix the
-problem.
-
-If you want to define a single-argument constructor, but you **don't** want
-the types to implicitly convert, you can define the constructor with a
-[keyword-only argument](/mojo/manual/functions#positional-only-and-keyword-only-arguments):
+In this case, you can fix the issue by explicitly casting to one of the
+intermediate types. For example:
 
 ```mojo
-struct Target:
-  # does not support implicit conversion
-  fn __init__(out self, *, source: Source): ...
-
-# the constructor must be called with a keyword
-var t = Target(source=a)
+var t = OverloadedTarget(A(Source())) # OK
 ```
 
-:::note
+Mojo applies at most one implicit conversion to a variable. For example:
 
-In the future we intend to provide a more explicit method of declaring whether
-a constructor should support implicit conversion.
+```mojo
+var t: OverloadedTarget = Source() # Error: can't implicitly convert Source
+                                   # to Target
+```
 
-:::
+Would fail because there's no direct conversion from `Source` to
+`OverloadedTarget`.
 
 ## Copy constructor