Add Documentation + Example Code for Getting Array Element from Function

[amarraff]

Your Godot version: v4.2.2.stable.official [15073afe3]

Issue description: One example is how the documentation for dictionaries and enums show how to print all keys and their values via the .keys() function, but doesn't mention that it's possible to access a single key at a given index of .keys(). In my case I was looking for syntax to do this, which I found information on at this forum post: https://forum.godotengine.org/t/taking-an-enum-name-instead-of-its-value/24261/3

The documentation page for Array may be a good place for this information.

URL to the documentation page (if already existing):

https://docs.godotengine.org/en/stable/classes/class_array.html

https://docs.godotengine.org/en/stable/classes/class_dictionary.html

https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_basics.html#enums

[AThousandShips]

This isn't standard and depends on the implementation of enums, don't think we should add this, especially as enums can have duplicate keys, you should probably use your own manual way to access these, like:

enum MyEnum {
    KEY_1 = 1,
    ...
}

func get_name(key: MyEnum) -> String:
    match key:
        KEY_1:
            return "KEY_1"
        ...

[amarraff]

This isn't standard and depends on the implementation of enums, don't think we should add this, especially as enums can have duplicate keys, you should probably use your own manual way to access these, like:

enum MyEnum {
    KEY_1 = 1,
    ...
}

func get_name(key: MyEnum) -> String:
    match key:
        KEY_1:
            return "KEY_1"
        ...

Thank you for the example code; perhaps it would make more sense for me to request an improvement to the engine itself via adding a get_key_name func, or something similar?

In my case, I have an enum called "Characters" and when I print their dialogue in a text box on screen, I print the name of the character enum. Before I came across the code in the forum post I linked, it was just printing the index of the enum. My code looks like this: print_debug(str(Enums.Characters.keys()[diob.character]) This shows me the name of the character the dialogue is relevant to when it begins printing, so I know the right character enum was assigned to the dialogue. It works for what I need, so I figured having it in the docs may help others; I'm unfamiliar with the duplicate keys you mentioned, is the issue linked to enum keys not needing an explicit index assignment when declared?

[AThousandShips]

It's fine to do this, but it's an implementation detail, so I would be a bit hesitant to document it

With duplicate keys you can easily have:

enum MyEnum {
    FOO = 1,
    BAR = 2,
    BAZ = 1,
}

That won't work in reverse, it won't work with match either but it's part of the limitations that make having an explicit method to look up things difficult, because there isn't a guarantee that MyEnum.find_key(BAZ) actually returns BAZ, in this case it would likely return FOO

[amarraff]

It's fine to do this, but it's an implementation detail, so I would be a bit hesitant to document it

With duplicate keys you can easily have:

enum MyEnum {
    FOO = 1,
    BAR = 2,
    BAZ = 1,
}

That won't work in reverse, it won't work with match either but it's part of the limitations that make having an explicit method to look up things difficult, because there isn't a guarantee that MyEnum.find_key(BAZ) actually returns BAZ, in this case it would likely return FOO

Right, I wasn't even aware that was a possibility. It would make sense to put a warning about duplicates next to the example, if documented.

If documenting it is a bad idea, that's okay. I just want to emphasize that I'd likely still be stuck if I didn't come across that forum post, so I thought perhaps an official mention of the syntax in the docs could be a good idea (if it's not already mentioned somewhere I missed).

[AThousandShips]

It's mentioned that they are implemented as dictionaries, and they have this method

What I'm saying is just that:

• It's an implementation detail
• It's not free of potential issues
• Most of the time you don't need or want to get the name of an enum, so usually a match is the way used

[amarraff]

It's mentioned that they are implemented as dictionaries, and they have this method

What I'm saying is just that:

• It's an implementation detail

• It's not free of potential issues

• Most of the time you don't need or want to get the name of an enum, so usually a match is the way used

I understand more now why you're hesitant to place it under the enums section as an example. It's just not information that was obvious to me despite my existing programming knowledge, so it may help others to have that implementation detail shown/explained somewhere in the docs if it isn't there already. It doesn't have to be under the enum section if that doesn't make sense.

I just tried searching the docs for )[, the symbols between the end of a given func and the beginning of an index query, but it didn't find any results.

I took a look at the documentation for arrays and dictionaries, but neither appears to show the syntax for accessing an index after typing a function which returns an array (at least that I'm seeing).

I think at least having this mentioned somewhere in the docs would be helpful information since the engine/language is capable of it, and there are use cases for it beyond my own. Something along the lines of "you can also access elements from functions that return arrays, like this:" followed by a short example code. I've updated the issue to be less specific.