@@ -15,10 +15,11 @@ features in Vim9 script.
15152. Differences| vim9-differences |
16163. New style functions| fast-functions |
17174. Types| vim9-types |
18- 5. Namespace, Import and Export| vim9script |
19- 6. Classes and interfaces| vim9-classes |
18+ 5. Generic functions| generic-functions |
19+ 6. Namespace, Import and Export| vim9script |
20+ 7. Classes and interfaces| vim9-classes |
2021
21- 9 . Rationale| vim9-rationale |
22+ 8 . Rationale| vim9-rationale |
2223
2324==============================================================================
2425
@@ -1895,7 +1896,146 @@ corresponding empty value.
18951896
18961897==============================================================================
18971898
1898- 5. Namespace, Import and Export
1899+ *generic-functions*
1900+ 5. Generic functions
1901+
1902+ A generic function allows using the same function with different type
1903+ arguments, while retaining type checking for arguments and the return value.
1904+ This provides type safety and code reusability.
1905+
1906+ Declaration~
1907+ *generic-function-declaration*
1908+ *E1552* *E1553* *E1558*
1909+ The type parameters for a generic function are declared in angle brackets "<"
1910+ and ">" directly after the function name. Multiple type names are separated
1911+ by commas:>
1912+
1913+ def[!] {funcname}<{type} [, {types}]>([arguments])[: {return-type}]
1914+ {function body}
1915+ enddef
1916+ <
1917+ These type parameters can then be used like any other type within the function
1918+ signature and body. Example:>
1919+
1920+ def MyFunc<T, A, B>(param1: T): T
1921+ var f: A
1922+ var x = param1
1923+ return x
1924+ enddef
1925+ <
1926+ *type-variable-naming* *E1551*
1927+ The convention is to use a single uppercase letter for a type variable (e.g.,
1928+ T, A, X), although longer names are allowed. The name must start with an
1929+ uppercase letter.
1930+
1931+ *E1557* *E1559*
1932+ A function must be declared and used either as generic or as a regular
1933+ function - but not both.
1934+
1935+ *E1560*
1936+ A type variable name must not conflict with other defined names, such as class
1937+ names, type aliases, enum names, function names or other type variable names.
1938+
1939+ Calling a generic function~
1940+ *generic-function-call*
1941+ To call a generic function, specify the concrete types in "<" and ">"
1942+ between the function name and the argument list:>
1943+
1944+ MyFunc<number, string, list<number>>()
1945+ <
1946+ *E1554* *E1555* *E1556*
1947+ The number of concrete types provided when calling a generic function must
1948+ match the number of type variables in the function. An empty type list is not
1949+ allowed. Any Vim9 type (| vim9-types | ) can be used as a concrete type in a
1950+ generic function.
1951+
1952+ Spaces are not allowed between the function name and "<", or between ">" and
1953+ the opening "(".
1954+
1955+ A generic function can be exported and imported like a regular function.
1956+ See| :export | and| :import | .
1957+
1958+ A generic function can be defined inside another regular or generic function.
1959+
1960+ Referencing type variables in generic types~
1961+
1962+ Instead of concrete types, type variables can be used with generic types.
1963+ This is useful for complex data structures like lists of dictionaries or
1964+ dictionaries of lists. Example:>
1965+
1966+ vim9script
1967+
1968+ def Flatten<T>(x: list<list<T>>): list<T>
1969+ var result: list<T> = []
1970+ for inner in x
1971+ result += inner
1972+ endfor
1973+ return result
1974+ enddef
1975+
1976+ echo Flatten<number>([[1, 2], [3]])
1977+ <
1978+
1979+ Generic class method~
1980+
1981+ A Vim9 class method can be a generic function:>
1982+
1983+ class A
1984+ def Foo<X, Y>()
1985+ enddef
1986+ endclass
1987+ var a = A.new()
1988+ a.Foo<number, string>()
1989+ <
1990+ *E1432* *E1433* *E1434*
1991+ A generic class method in a base class can be overridden by a generic method
1992+ in a child class. The number of type variables must match between both
1993+ methods. A concrete class method cannot be overridden by a generic method,
1994+ and vice versa.
1995+
1996+ Generic function reference~
1997+
1998+ A function reference (| Funcref | ) can be a generic function. This allows for
1999+ creating factories of functions that operate on specific types:>
2000+
2001+ vim9script
2002+
2003+ def MakeEcho<T>(): func(T): T
2004+ return (x: T): T => x
2005+ enddef
2006+
2007+ var EchoNumber = MakeEcho<number>()
2008+ echo EchoNumber(123)
2009+
2010+ var EchoString = MakeEcho<string>()
2011+ echo EchoString('abc')
2012+ <
2013+ Compiling and Disassembling Generic functions~
2014+
2015+ The| :defcompile | command can be used to compile a generic function with a
2016+ specific list of concrete types:>
2017+
2018+ defcompile MyFunc<number, list<number>, dict<string>>
2019+ <
2020+ The| :disassemble | command can be used to list the instructions generated for
2021+ a generic function:>
2022+
2023+ disassemble MyFunc<string, dict<string>>
2024+ disassemble MyFunc<number, list<blob>>
2025+ <
2026+ Limitations and Future Work~
2027+
2028+ Currently, Vim does not support:
2029+ - Type inference for type variables: All types must be explicitly specified
2030+ when calling a generic function.
2031+ - Type constraints: It's not possible to restrict a type variable to a
2032+ specific class or interface (e.g., `T extends SomeInterface`).
2033+ - Default type arguments: Providing a default type for a type parameter
2034+ when not explicitly specified.
2035+
2036+ ==============================================================================
2037+
2038+ 6. Namespace, Import and Export
18992039*vim9script* *vim9-export* *vim9-import*
19002040
19012041A Vim9 script can be written to be imported. This means that some items are
@@ -2174,7 +2314,7 @@ Or: >
21742314
21752315==============================================================================
21762316
2177- 6 . Classes and interfaces*vim9-classes*
2317+ 7 . Classes and interfaces*vim9-classes*
21782318
21792319In legacy script a Dictionary could be used as a kind-of object, by adding
21802320members that are functions. However, this is quite inefficient and requires
@@ -2188,7 +2328,7 @@ functionality it is located in a separate help file: |vim9class.txt|.
21882328
21892329==============================================================================
21902330
2191- 9 . Rationale*vim9-rationale*
2331+ 8 . Rationale*vim9-rationale*
21922332
21932333The :def command~
21942334