Skip to content

CEP-0011: General Extension Methods

Draft

Draft proposal for general extension methods. V1 has inherent methods and visible contract-operation method lookup, but no arbitrary extension-method declarations.

Summary

Catalyst should eventually support general extension methods so library code can attach ordinary method-call ergonomics to types it does not own, including primitive and built-in type forms, without making those names compiler magic.

V1 keeps this narrower:

  • inherent methods live with the receiver type;
  • visible semantic contract operations can participate in method-call lookup;
  • selected primitive and built-in operations may be compiler-owned methods until extension methods exist.

Motivation

Several V1 decisions intentionally use sharp compiler-owned helper methods on primitive or built-in surfaces, such as opaque pointer recovery and numeric conversion helpers. That keeps V1 implementable, but it is not the ideal long-term layering.

General extension methods would let Catalyst move these helpers toward ordinary prelude or standard-library declarations while preserving method-call ergonomics.

Example

Possible future shape:

extension i32 {
  fn clamp_nonnegative(self: i32) i32 {
    if self < 0 {
      return 0
    }
    return self
  }
}

const value = delta.clamp_nonnegative()

This is different from V1 inherent methods because the extension is declared outside the primitive type's owner.

Proposed Direction

The future design should cover:

  • extension methods declared outside the receiver type;
  • coherence and visibility rules for imported extension methods;
  • precedence between fields, inherent methods, contract operations, and extension methods;
  • ambiguity diagnostics and qualified-call escape hatches;
  • extension methods on primitive types and built-in type forms;
  • whether extension methods can satisfy or forward semantic contract operations;
  • how extension methods appear in reflection, docs, autocomplete, and source navigation.

Extension methods should not silently change layout, ownership, allocation, or dispatch. Method-call syntax remains call syntax; the underlying declaration should stay inspectable.

V1 Compatibility

V1 method lookup remains limited to inherent members and visible contract operations. Primitive helper methods that cannot yet be expressed as ordinary declarations should be documented as V1 compiler-owned surface with this CEP as the migration path.