Export fieldindex (JuliaLang#58119)

At present, we export `Base.fieldname`, which maps a field's index to
its symbol. Although we have the inverse function, `Base.fieldindex`,
which maps a field's symbol to its index, defined and documented, we
currently do not export it.

This PR changes this and exports it to enhance the consistency and
completeness of the field introspection functions. Additionally, it is
unlikely that the function will undergo fundamental changes in the
future, so exporting it should not pose a significant maintenance
burden. The interface is likely fully defined by the following two
properties.

```julia
@test fieldname(Some{Int}, Base.fieldindex(Some{Int}, :value)) === :value
@test Base.fieldindex(Some{Int}, fieldname(Some{Int}, 1)) === 1
```

Besides doing the `export`, this PR adapts the documentation and adds
test cases.

Fixes JuliaLang#58092

Thanks to @nsajko for the support in covering all artifacts.

Author: PatrickHaecker

NEWS.md

@@ -24,6 +24,8 @@ Build system changes
 New library functions
 ---------------------
 
+* Exporting function `fieldindex` to get the index of a struct's field ([#58119]).
+
 New library features
 --------------------
 

base/exports.jl

@@ -807,6 +807,7 @@ export
     fieldoffset,
     fieldname,
     fieldnames,
+    fieldindex,
     fieldcount,
     fieldtypes,
     hasfield,

base/runtime_internals.jl

@@ -1057,7 +1057,7 @@ String
 fieldtype
 
 """
-    Base.fieldindex(T, name::Symbol, err:Bool=true)
+    fieldindex(T, name::Symbol, err:Bool=true)
 
 Get the index of a named field, throwing an error if the field does not exist (when err==true)
 or returning 0 (when err==false).
@@ -1069,14 +1069,20 @@ julia> struct Foo
            y::String
        end
 
-julia> Base.fieldindex(Foo, :z)
+julia> fieldindex(Foo, :y)
+2
+
+julia> fieldindex(Foo, :z)
 ERROR: FieldError: type Foo has no field `z`, available fields: `x`, `y`
 Stacktrace:
 [...]
 
-julia> Base.fieldindex(Foo, :z, false)
+julia> fieldindex(Foo, :z, false)
 0
 ```
+
+!!! compat "Julia 1.13"
+    This function is exported as of Julia 1.13.
 """
 function fieldindex(T::DataType, name::Symbol, err::Bool=true)
     return err ? _fieldindex_maythrow(T, name) : _fieldindex_nothrow(T, name)

doc/src/base/base.md

@@ -207,6 +207,7 @@ Base.isstructtype
 Base.nameof(::DataType)
 Base.fieldnames
 Base.fieldname
+Base.fieldindex
 Core.fieldtype
 Base.fieldtypes
 Base.fieldcount

test/reflection.jl

@@ -361,6 +361,10 @@ tlayout = TLayout(5,7,11)
 @test fieldtype(Union{Tuple{Char},Tuple{Char,Char}},2) === Char
 @test_throws BoundsError fieldtype(Union{Tuple{Char},Tuple{Char,Char}},3)
 
+@test [fieldindex(TLayout, i) for i = (:x, :y, :z)] == [1, 2, 3]
+@test fieldname(TLayout, fieldindex(TLayout, :z)) === :z
+@test fieldindex(TLayout, fieldname(TLayout, 3)) === 3
+
 @test fieldnames(NTuple{3, Int}) == ntuple(i -> fieldname(NTuple{3, Int}, i), 3) == (1, 2, 3)
 @test_throws ArgumentError fieldnames(Union{})
 @test_throws BoundsError fieldname(NTuple{3, Int}, 0)