Estructuras en Solidity

En este tutorial aprenderás a declarar y manipular estructuras en Solidity. Veremos también algunos de los usos más habituales de las estructuras junto con algunos ejemplos más complejos, como la declaración de arrays de estructuras o mappings de estructuras.

Qué es una estructura

Las estructuras se usan para representar datos estructurados en los Smart Contracts. Te permitirán definir una plantilla conformada por diferentes campos que representarán aquellos datos que desees organizar o almacenar.

Se trata de un concepto muy parecido al de las clases de JavaScript, aunque en este caso las estructuras son más limitadas. Una vez definida la plantilla de la estructura, podrás crear varias estancias de la misma que sigan la definición que has establecido. Una gran diferencia con las clases de PHP o de JavaScript es que no podrás definir métodos en el interior de una estructura, sino que únicamente podrás establecer campos o propiedades.

Cuándo usar una estructura

Por lo general, podría ser conveniente usar estructuras si detectas que estás usando demasiadas propiedades o si lo que quieres es crear una jerarquía de valores. Del mismo modo, podría ser interesante el uso de estructuras cuando quieras encapsular cierta información mediante una única referencia.

Cómo declarar estructuras

Para declarar una estructura debes usar la sentencia struct seguida del nombre de la estructura y de sus propiedades entre llaves. Las propiedades de una estructura conforman su cuerpo y se definirán entre una llave de apertura y otra de cierre. Las propiedades se definen en el cuerpo de la estructura al igual que cualquier otra variable. Cada definición deberá terminar en punto y coma.

En el siguiente ejemplo definimos la estructura Usuario, que contendrá cuatro propiedades, que son el nombre, el apellido, la dirección y el número de puntos de un usuario:

struct Usuario {
    string nombre;
    string apellido;
    address direccion;
    uint puntos;
}

Vamos a crear un Smart Contract y a definir la estructura anterior dentro del mismo, de modo que podamos usarla como ejemplo en el resto de esta guía:

pragma solidity ^0.8.0;

contract MiContrato
{
    struct Usuario {
        string nombre;
        string apellido;
        address direccion;
        uint puntos;
    }
}

Por ahora únicamente hemos definido la estructura. Todavía no podemos trabajar con ella, ya que para eso tendremos que crear instancias de la misma, dando valores a sus propiedades.

Cómo instanciar una estructura

A continuación vamos a ver cómo crear instancias de una estructura, que es algo que podrás realizar de diversas formas. Para crear una instancia de una estructura debes indicar el nombre de la estructura como si se tratase de un tipo, luego debes indicar el método de almacenamiento, que por ejemplo podría ser memory o storage.

Luego debes indicar el identificador de la estructura y finalmente debes referenciar la estructura de un modo similar al que sigues cuando invocas una función, pasándole los valores que tendrán sus propiedades, en el mismo orden en el que han sido definidas.

Usuario memory usuario = Usuario('Edu', 'Lazaro', msg.sender, 0);

También podrías crear otra instancia de la estructura Usuaro:

Usuario memory usuario2 = Usuario({ nombre: 'Edu', apellido: 'Lazaro', direccion: msg.sender, puntos: 0});

Existe otra notación mediante la cual podrás crear una instancia de una estructura. Esta notación es muy parecida a la que se suele usar a la hora de crear objetos literales  en JavaScript; es decir, tendrás que indicar los pares de clave y valor de las propiedades entre llaves:

Usuario memory usuario2 = Usuario('Edu', 'Lazaro', msg.sender, 0);

En el siguiente ejemplo creamos una instancia de la estructura Usuario con los valores que pasamos como argumentos a la función crearUsuario:

function crearUsuario(string calldata _nombre, string calldata _apellido, uint _puntos) external view returns (Usuario memory)
{
    Usuario memory usuario = Usuario(_nombre, _apellido, msg.sender, _puntos);
    return usuario;
}

Cómo acceder a una instancia de una estructura

Una vez hayas creado una instancia de una estructura, podrás acceder al valor de sus propiedades del mismo modo en el que accedes a las propiedades de un objeto en JavaScript. Es decir; tendrás que usar el identificador de la estructura seguido de un punto y del nombre de la propiedad que quieras obtener:

usuario.nombre;

Cómo actualizar una instancia de una estructura

Una vez hayas creado una instancia de una estructura, también podrás modificar el valor de sus propiedades asignándoles un valor:

usuario.nombre = 'Aurelio';

Cómo eliminar una instancia de una estructura

Para eliminar una instancia de una estructura tendrás que usar la sentencia delete seguida del nombre de la estructura:

delete usuario:

Cómo crear un array de estructuras

Antes de continuar, decir que si no sabes cómo funcionan los arrays en Solidity, es recomendable que consultes la guía en donde explico qué es un array y cómo se usa. Para crear un array de estructuras, basta con que indiques el nombre de la estructura tal y como si fueses a indicar el tipo de los elementos del array. En el siguiente ejemplo definimos un array de tipo Usuario:

Usuario[] usuario;

Vamos a modificar nuestro contrato agregando la definición del array de usuarios:

pragma solidity ^0.8.0;

contract MiContrato
{
    struct Usuario {
        string nombre;
        string apellido;
        address direccion;
        uint puntos;
    }
    Usuario[] usuarios;
}

Ahora vamos a crear una función que agregue una nueva instancia de una estructura al array de estructuras que hemos creado. Para ello usaremos el método push que incluyen los arrays:

usuarios.push(usuario);

Vamos a crear una función que agregue una estructura a nuestro array de estructuras:

function agregarUsuario(string calldata _nombre, string calldata _apellido, uint _puntos) external
{
    Usuario memory usuario = Usuario(_nombre, _apellido, msg.sender, _puntos);
    usuarios.push(usuario);
}

Cómo crear un mapping de estructuras

También puedes crear un mapping de estructuras. Si no sabes qué es un mapping, consulta la guía en donde explico qué es un mapping y cómo se usa. Para declarar un mapping de estructuras sencillamente debes declarar el mapping usando el nombre de la estructura como tipo de valor que contendrá el mapping:

mapping(address => Usuario) informacion;

A modo de ejemplo vamos a agregar un mapping a nuestro contrato que nos permita asociar las direcciones de cada usuario con la información de dichos usuarios, almacenada en instancias de la estructura Usuario:

pragma solidity ^0.8.0;

contract MiContrato
{
    struct Usuario {
        string nombre;
        string apellido;
        address direccion;
        uint puntos;
    }
    mapping(address => Usuario) informacion;
}

Para agregar una estructura a un mapping, tendrás que usar el identificador del mapping y también la clave que quieres usar para asociar la instancia del mapping con la instancia de estructura.

En el siguiente ejemplo crearemos una función que asocia la dirección de un usuario con la información personal del mismo:

function agregarInformacion(string calldata _nombre, string calldata _apellido, uint _puntos) external
{
    Usuario memory usuario = Usuario(_nombre, _apellido, msg.sender, _puntos);
    informacion[msg.sender] = usuario;
}

Esto ha sido todo.

---