Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

#

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Enrich document with using getter function over state struct instance #15526

Open
wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

Enrich document with using getter function over state struct instance #15526

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 61 additions & 26 deletions docs/contracts/visibility-and-getters.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -157,19 +157,19 @@ it evaluates to a state variable. If it is accessed externally
}
}

When considering arrays, mapping, and structs, the getter functions do not return
the entire state variable.
Comment on lines +160 to +161
Copy link
Member

@cameel cameel Mar 21, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I originally suggested to make things more concise here and merge the examples into one. I think things were going in that direction, but looking at the PR now, it seems that we went full circle and still ended up with multiple examples again :)

So a new suggestion: let's put everything starting from this place into a new subsection called Getters for Complex Types. That will at least separate these details from the main description of getters.

Then I'd expand this bit into an intro paragraph, along these lines:

Suggested change
When considering arrays, mapping, and structs, the getter functions do not return
the entire state variable.
Returning the entire data structure from a getter function in one go can be very expensive and in case of mappings outright impossible.
For this reason the return type of a getter will sometimes differ from the type of the state variable.
The general rule is that getters for arrays and mappings will return only one element at a time and certain fields can be omitted from structs.
This section will explain those rules in more detail.
Note that this mechanism is not meant to prevent the contract from returning the whole value, but simply to make
the default way to do this more aligned with best practices.
There are situations where returning the original type is perfectly acceptable and it can be easily achieved
by manually defining an external function that returns it.


If you have a ``public`` state variable of array type, then you can only retrieve
single elements of the array via the generated getter function. This mechanism
exists to avoid high gas costs when returning an entire array. You can use
arguments to specify which individual element to return, for example
``myArray(0)``. If you want to return an entire array in one call, then you need
to write a function, for example:
exists to avoid high gas costs when returning an entire array.

.. code-block:: solidity

// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.16 <0.9.0;

contract arrayExample {
contract ArrayExample {
// public state variable
uint[] public myArray;

Expand All @@ -186,39 +186,74 @@ to write a function, for example:
}
}

Now you can use ``getArray()`` to retrieve the entire array, instead of
``myArray(i)``, which returns a single element per call.
If you have a ``public`` state variable of mapping type. The getter function
returns the value associated with the key passed as an argument.

.. code-block:: solidity

// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.16 <0.9.0;

contract MappingExample {
// public state variable
mapping(uint => uint) public myMap;

// Getter function generated by the compiler
/*
function myMap(uint i) public view returns (uint) {
return myMap[i];
}
*/
}

The next example is more complex:
When you declare a public state variable of a struct type, the generated getter function
returns each member of the struct as separate elements within a tuple,
rather than the struct as a single object in memory.
Comment on lines +209 to +211
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When you declare a public state variable of a struct type, the generated getter function
returns each member of the struct as separate elements within a tuple,
rather than the struct as a single object in memory.
When you declare a public state variable of a struct type, the generated getter function
returns members of the struct as separate elements within a tuple,
rather than the struct as a single object.

The members returned appear in the order they are declared in the struct, provided they
are not omitted. The mapping and arrays (with the exception of byte arrays)
in the struct are omitted because there is no good way to
select individual array members or provide a key for the mapping
Additionally, if all struct members are omitted, no getter function will be generated.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should clarify that this is a compilation error. The compiler won't just silently skip the getter.


.. code-block:: solidity

// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.0 <0.9.0;
pragma solidity >=0.4.16 <0.9.0;

contract Complex {
struct Data {
contract StructExample {
// Struct Definition with single member
struct SimpleStruct {
int[2] arr;
mapping(uint => uint) map;
}

// Struct Definition with multiple members
struct ComplexStruct {
uint a;
bytes3 b;
mapping(uint => uint) map;
uint[3] c;
uint[] d;
bytes e;
}
mapping(uint => mapping(bool => Data[])) public data;
Comment on lines +230 to -208
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assuming the suggestions above are applied, I'd be fine with merging it, since it's already an improvement over what we had. But I also think the structure could be better and there a lot more details we could add.

As for the structure, I'd rather incorporate the relevant parts of the complex example into the respective types. For example we should show multi-dimensional arrays already in the initial array example.

As for missing details, I played with this a bit and I think this is a more complete list of corner cases here:

  1. Internal types (e.g. internal function pointers)
    • Cannot be the return type (compilation error).
  2. Arrays
    • n-dimensional array getters have n parameters.
    • bytes and string getters return the whole thing.
    • Elements cannot be of internal or recursive types (compilation error).
  3. Mappings
    • Elements cannot be of internal or recursive types (compilation error).
  4. Structs
    • Top-level struct gets unpacked into a tuple.
    • Fields of mapping types are omitted from the top-level struct.
      • But not omitted from nested structs (compilation error).
    • Fields of array types are omitted from the top-level struct.
      • But not omitted from nested structs (no error)
    • Fields of internal types are not omitted but cannot be returned (compilation error).
      • Unless they are elements of an array/mapping that would be omitted. Then they are omitted along with their container.
    • Fields of recursive types (e.g. a dynamic array or mapping with elements of that same struct type) are not omitted but cannot be returned (compilation error).
      • Unless they are elements of an array/mapping that would be omitted. TThen they are omitted along with their container.

Note that an array/mapping/struct containing an internal/recursive type is itself considered internal/recursive.

So my proposal would be to have one example for each of these four categories, showing both a simple case and the corner cases.

In any case, this PR has been stalled long enough so I won't block it if the above is not done, but that's basically how this section should look like in my opinion.

}

It generates a function of the following form. The mapping and arrays (with the
exception of byte arrays) in the struct are omitted because there is no good way
to select individual struct members or provide a key for the mapping:

.. code-block:: solidity
// public state variables
// SimpleStruct omits all its members, therefore its public instance is disallowed
ComplexStruct public complexStruct;
mapping(uint => mapping(bool => ComplexStruct[])) public map;

function data(uint arg1, bool arg2, uint arg3)
public
returns (uint a, bytes3 b, bytes memory e)
{
a = data[arg1][arg2][arg3].a;
b = data[arg1][arg2][arg3].b;
e = data[arg1][arg2][arg3].e;
}
// Getter function generated by the compiler
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be nice to keep the explanation from before (with the correction i suggested in #15526 (comment)):

The mapping and arrays (with the exception of byte arrays)
in the struct are omitted because there is no good way to
select individual array members or provide a key for the mapping

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

have changed based on my understanding. plz check

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
// Getter function generated by the compiler
// Getter functions generated by the compiler

/*
function complexStruct() public view returns (uint, bytes3, bytes memory) {
return (complexStruct.a, complexStruct.b, complexStruct.e);
}
function map(uint arg1, bool arg2, uint arg3)
public
returns (uint a, bytes3 b, bytes memory e)
{
a = map[arg1][arg2][arg3].a;
b = map[arg1][arg2][arg3].b;
e = map[arg1][arg2][arg3].e;
}
*/
}