`$map.put`¶

Description¶

Ajoute ou met à jour un élément dans le map.

Note

Le langage de script implémente nativement la fonctionnalité via les notations map.key ou map["key"]. Voir les exemples plus pour le détail.

Map passé par valeur ou référence

Attention, l'impact de la méthode sur l'objet map varie selon qu'il soit passé par valeur ou par référence en paramètre. Pour rappel, les objets sont systématiquement passés par valeur en paramètre de méthodes (à l'exception des objets pojo). Cela signifie que la méthode reçoit une copie de l'objet de départ.

Il est possible de forcer un passage d'objet en référence au moyen du préfixe &.

Lorsque le map est passé par valeur, la méthode ne modifie pas l'objet de départ, elle ne fait que de construire un nouvel objet intégrant le nouvel élément à ajouter. Lorsque le map est passé par référence, la méthode est capable de le modifier. Les exemples données plus bas reviennent sur cette notion.

Comme le fait d'utiliser la notation par référence peut facilement être oublié, l'usage de $data.put n'est pas recommandé. Les notations map.key ou map["key"] sont donc à privilégier.

Syntaxe¶

$map.put( map , key , value )

Paramètres¶

map map: Map à traiter
key string: Nom du membre à rechercher
value any: Valeur à inscrire dans le map

Retour¶

Retourne la valeur associée à key avant qu'elle ne soit mise à jour dans le map. Retourne null si la clé n'existait pas dans le map.

Exemple¶

var map = { a: 1, b: 2 };
$logger.info(map);

$logger.info("exemples de get");
$logger.info($map.get(map, "a"));
$logger.info(map.a);
$logger.info(map["a"]);

$logger.info("exemples de put");
$logger.info($map.put(map, "c", 3));    // cet appel ne modifie pas `map`
$logger.info("résultat passage par valeur: ${map}");
$logger.info($map.put(&map, "c", 3));    // passage par référence
$logger.info("résultat passage par référence: ${map}");

// notation "put" simplifiée
map.d = 4;
map["e"] = 5;
$logger.info("résultat notation simplifiée: ${map}");

Log correspondant à l'exemple ci-dessus:

{"a": 1, "b": 2}
exemples de get
1
1
1
exemples de put
null
résultat passage par valeur: {"a": 1, "b": 2}
null
résultat passage par référence: {"a": 1, "b": 2, "c": 3}
résultat notation simplifiée: {"a": 1, "b": 2, "c": 3, "d": 4, "e": 5}

Modification d'API

De base les méthodes fournies par Ewt sont "immutables". Cela signifie qu'il n'est pas possible de les modifier. Ainsi, l'instruction suivante provoquera une erreur:

$logger.info = function(x) { $logger.warn(x); };

Cette instruction cherche à redéfinir le fonctionnement de la méthode $logger.info, ce qui n'est pas permis de base.

Cependant, la méthode $map.put permet de bypasser cette règle. Ainsi l'instruction suivante permettra de réaliser l'opération:

$map.put(&$logger, "info", function(x) { $logger.warn(x); });
$logger.info("test");       // affiche désormais un warn !

La méthode n'est pas modifiée de façon permanente, mais uniquement pour le traitement en cours.

L'opération est permise dans la version actuelle du moteur, mais il n'est pas exclu que cela soit retiré dans les versions futures.

$map.put¶