Objet Dictionary  
 
Createable

Oui

 
Bibliothèque

Microsoft Scripting Runtime

 
Description

L'objet Dictionary est identique à l'objet Collection, sauf qu'il se base généralement sur la table associative Perl. Tout comme une table ou un objet Collection, l'objet Dictionary conserve des éléments appelés éléments ou membres contenant des données. Un objet Dictionary peut contenir tous les types de données possibles, y compris des objets et d'autres objets Dictionary. Pour accéder à la valeur de ces éléments de dictionnaire, il faut utiliser des clés uniques (ou valeurs nommées) stockées avec les données plutôt que d'utiliser une position ordinale des éléments comme c'est le cas avec une table. L'objet Dictionary est donc idéal pour accéder à des données associées à une valeur nommée unique.

Vous pouvez accéder à tous les éléments stockés dans un objet Dictionary au moyen de l'élément For Each ...Next. Cependant, au lieu de renvoyer une variante contenant la valeur des données stockée dans l'objet Dictionary comme attendu, il renvoie une variante contenant la clé associée au membre. Il suffit ensuite de transmettre cette clé à la méthode Item pour récupérer le membre, comme illustré dans l'exemple suivant :

Dim vKey 
Dim sItem, sMsg 
Dim oDict 
    
Set oDict =  CreateObject("Scripting.Dictionary")
oDict.Add "One", "Engine"
oDict.Add "Two", "Wheel"
oDict.Add "Three", "Tire"
oDict.Add "Four", "Spanner"
        
For Each vKey In oDict
   sItem = oDict.Item(vKey)
   sMsg = sMsg & sItem & vbCrLf
Next
   
MsgBox sMsg
 
Propriétés de l'objet Dictionary

L'objet Dictionary possède les quatre propriétés suivantes :

Property

Description

CompareMode

Détermine l'ordre des comparaisons de texte dans la propriété Item

Count

Indique le nombre total d'éléments figurant dans le dictionnaire

Item

Définit ou récupère un élément de donnée particulier dans le dictionnaire

Key

Renomme une clé existante

 
Méthodes de l'objet Dictionary

L'objet Dictionary prend en charge les cinq méthodes suivantes :

Property

Description

Add

Ajoute un élément et la clé qui lui est associée au dictionnaire

Exists

Détermine l'existence d'une clé particulière dans le dictionnaire

Keys

Renvoie toutes les clés figurant dans le dictionnaire

Remove

Supprime un élément du dictionnaire

Remove All

Supprime toutes les données du dictionnaire

Méthode Dictionary.Add  
 
 
Syntaxe
dictionaryobject.Add clé, élément
dictionaryobject

Utilisation : Obligatoire

Type de données : Objet Dictionary

Une référence à un objet Dictionary.

key

Utilisation : Obligatoire

Type de données : Quelconque

Une valeur clé unique figurant dans l'objet Dictionary.

item

Utilisation : Obligatoire

Type de données : Quelconque

L'élément à ajouter au dictionnaire.

 
Description

Ajoute une clé et l'élément qui lui est associé à l'objet Dictionary spécifié.

 
Les règles en bref
  • Si la clé n'est pas unique, l'erreur d'exécution 457, "Cette clé est déjà associée à un élément de la collection," est générée.

  • item peut être de tout type de données, y compris des objets et d'autres objets Dictionary.

 
Exemple

L'exemple utilise un objet Dictionary pour enregistrer des abréviations d'état et les noms d'état correspondants :

Dim StateCode, StateName
Dim StateDict
Dim Key

Set StateDict = CreateObject("Scripting.Dictionary")

StateCode = "CA"
StateName = "California"
StateDict.Add StateCode, StateName

StateCode = "NY"
StateName = "New York"
StateDict.Add StateCode, StateName

StateCode = "MI"
StateName = "Michigan"
StateDict.Add StateCode, StateName

Key = "NY"
MsgBox StateDict.Item(Key)
 
Conseils de programmation et pièges
  • L'ordre des membres dans un objet Dictionary est oficiellement non défini. Autrement dit, vous ne pouvez ni contrôler la position des différents membres ni les récupérer en fonction de leur position dans l'objet Dictionary. Pour résumer, votre code ne doit faire aucune hypothèse quant à la position des différents éléments figurant dans les objets Dictionary.

  • Après avoir ajouté une clé et l'élément de données qui lui est associé, vous pouvez modifier la clé à l'aide de la propriété Key en écriture seule.

  • Utilisez l'objet Dictionary pour stocker des tables de données, et tout particulièrement pour stocker des éléments de données simples auxquels une valeur clé peut accéder.

  • L'utilisation de l'objet Dictionary pour stocker des enregistrements de données à champs multiples n'est pas recommandée ; en revanche, les classes offrent de bien meilleures solutions de programmation. Pour stocker un enregistrement, il faut généralement ajouter au dictionnaire une table représentant les valeurs des champs de l'enregistrement. Cette méthode de programmation, qui consiste à affecter des tables à des éléments de l'objet Dictionary, n'est cependant pas très appropriée puisque les différents éléments de la table ne peuvent pas être modifiés directement une fois qu'ils sont affectés au dictionnaire.

 
Voir aussi

Propriété Dictionary.Key

 
Propriété Dictionary.CompareMode  
 
 
Type de données

Long

 
Description

Définit ou renvoie le mode utilisé pour comparer les clés dans un objet Dictionary.

 
Les règles en bref
  • La propriété CompareMode ne peut être définie que sur un dictionnaire ne contenant aucune donnée.

  • La propriété CompareMode peut posséder l'une ou l'autre des deux valeurs suivantes :

    0, Binaire

    Il s'agit de la valeur par défaut. Elle compare les clés octet par octet à l'aide d'une chaîne pour déterminer s'il existe ou non une correspondance.

    1, Texte

    Utilise une comparaison insensible à la casse lors de la tentative de mise en correspondance des clés au moyen d'une chaîne.

  • En outre, la valeur de la propriété CompareMode peut être supérieure à 2, auquel cas elle définit l'identificateur des paramètres régionaux (LCID) à utiliser lors de la comparaison.
 
Conseils de programmation et pièges
  • La propriété CompareMode ne doit être définie que si vous ne souhaitez pas utiliser le mode de comparaison binaire par défaut.

  • La bibliothèque de type Scripting Runtime définit les constantes (BinaryCompare et TextCompare) pouvant être utilisées pour remplacer leurs équivalents numériques. Vous pouvez pour cela utiliser l'une des trois méthodes suivantes. Vous pouvez définir les constantes vous-même en ajoutant le code suivant à votre script :

    Const BinaryCompare = 0
    Const TextCompare = 1

    Vous pouvez également utiliser les constantes vbBinaryCompare et vbTextCompare équivalentes définies dans la bibliothèque VBScript.

    Enfin, si vous êtes programmeur ASP, vous pouvez utiliser la directive METADATA pour accéder à la bibliothèque de type Scripting Runtime ; si vous développez un script WSH (Windows Script Host), vous pouvez inclure la ligne suivante dans un fichier Windows Script Host (.wsf ) pour pouvoir accéder aux constantes depuis la bibliothèque de type Scripting Runtime :

    <reference GUID="{420B2830-E718-11CF-893D-00A0C9054228}" />
  • Concrètement, la propriété CompareMode indique si la comparaison entre les noms de clé existants et l'argument clé de la méthode Add, de la méthode Exists, de la propriété Item ou de la propriété Key de l'objet Dictionary respecteront (BinaryCompare) ou non (TextCompare) la casse. Par défaut, les comparaisons respectent la casse.

 
Propriété Dictionary.Count  
 
 
Type de données

Long

 
Description

Une propriété en lecture seule qui renvoie le nombre de paires clé-élément d'un objet Dictionary.

 
Les règles en bref

Cette propriété renvoie le nombre effectif d'éléments figurant dans le dictionnaire Par conséquent, si vous utilisez la propriété Count pour itérer les éléments du dictionnaire, vous utiliserez un code similaire à celui-ci :

Dim ctr
For ctr = 0 to dictionary.Count - 1
   ' do something
Next
 
Méthode Dictionary.Exists  
 
 
Syntaxe
dictionaryobject.Exists(key) 
dictionaryobject

Utilisation : Obligatoire

Type de données : Objet Dictionary

Une référence à un objet Dictionary.

key

Utilisation : Obligatoire

Type de données : Chaîne

La valeur clé recherchée.

 
Valeur renvoyée

Booléenne

 
Description

Détermine si une clé donnée est présente ou non dans un objet Dictionary.

 
Les règles en bref

Renvoie la valeur True si la clé spécifiée figure dans l'objet Dictionary ; la valeur False dans le cas contraire.

 
Conseils de programmation et pièges
  • Si vous tentez d'utilisez la propriété Item pour renvoyer l'élément d'une clé non existante, ou si vous affectez une nouvelle clé à une clé non existante, la clé non existante est ajoutée au dictionnaire accompagnée d'un élément vierge. Pour éviter cela, vous devez utiliser la propriété Exists afin de vérifier que la clé figure dans le dictionnaire avant de poursuivre.

  • Le paramètre de la propriété CompareMode de l'objet Dictionary détermine la manière dont la key est comparée aux valeurs clé existantes.

 
Exemple
If oDict.Exists(strOldKey) Then
    oDict.Key(strOldKey) = strNewKey
End If   
 
Propriété Dictionary.Item  
 
 
Syntaxe

La syntaxe permettant de paramètrer un élément est la suivante :

dictionaryobject.Item(key) = item

La syntaxe permettant de renvoyer un élément est la suivante :

value = dictionaryobject.Item(key)
dictionaryobject

Utilisation : Obligatoire

Type de données : Objet Dictionary

Une référence à un objet Dictionary.

clé

Utilisation : Obligatoire

Type de données : Chaîne

Une clé unique de type chaîne pour cet objet Dictionary.

item

Utilisation : Facultatif

Type de données : Quelconque

Les données associées à la valeur key.

 
Type de données

Quelconque

 
Description

Définit ou renvoie l'élément de données à relier à une clé spécifiée dans un objet Dictionary.

 
Les règles en bref
  • La propriété Item correspond au membre par défaut de l'objet Dictionary.

  • Le type de données correspond à celui de l'élément renvoyé.

  • Contrairement à la propriété Item de la plupart des objets, celle de l'objet Dictionary possède un accès lecture-écriture. Si vous tentez d'affecter l'élément à une clé non existante, la clé est ajoutée au dictionnaire, et l'élément lui est associé, un peu comme un "ajout implicite."

 
Conseils de programmation et pièges
  • L'objet Dictionary ne vous permet pas de récupérer un élément en fonction de sa position ordinale.

  • Si vous indiquez une clé non existante lors de la tentative de récupération d'un élément, le dictionnaire manifeste un comportement plutôt étrange : il ajoute la valeur clé à l'objet Dictionary accompagnée d'un élément vierge. Vous devez donc utiliser la méthode Exists avant de paramétrer ou renvoyer un élément, comme illustré dans l'exemple.

  • Si l'élément à affecter ou à récupérer dans l'objet Dictionary est lui-même un objet, assurez-vous de bien utiliser le mot de passe Set lorsque vous l'affectez à une variable ou à l'objet Dictionary.

  • La comparaison de la valeur clé avec les clés des membres est définie par la valeur de la propriété CompareMode de l'objet Dictionary.

  • Malgré les inconvénients que présente l'aspect lecture-écriture de la propriété Item de l'objet Dictionary, elle a également ses avantages. Elle facilite notamment l'écrasement ou le remplacement d'un élément de données existant grâce à la fonction lecture-écriture de sa propriété Item : il vous suffit d'affecter la nouvelle valeur comme vous le feriez avec toute autre propriété.

  • L'objet Dictionary ne doit jamais être utilisé pour stocker un format HTML ou des données de requête dans une étendue Session d'une application ASP. L'objet Dictionary étant un objet COM de type apartment-threaded, ceci a pour conséquence de verrouiller l'application sur un thread d'exécution simple.

 
Exemple

L'exemple utilise l'objet Dictionary comme table de recherche pour récupérer le nom d'état correspondant au code d'état saisi par l'utilisateur. La page HTML contenant les informations utilisateur que reçoit le serveur se présente comme suit :

<HTML>
<HEAD><TITLE>Dictionary Object Example</TITLE></HEAD>
<BODY>
Enter your name and location: <P>
<FORM METHOD=POST ACTION=dictobj.asp>
Your name:
<INPUT TYPE="Text" NAME="VisitorName" /><P>
Your location:
<INPUT TYPE="Text" NAME="City" />,
<INPUT TYPE="Text" NAME="State" SIZE=2 /> <P>
<INPUT TYPE="Submit" VALUE="Submit" />
</FORM>
<BODY>
</HTML>

La page ASP qui récupère les informations fournies par l'utilisateur, les code et utilise l'objet Dictionary pour récupérer le nom d'état complet se présente comme suit :

<HTML>
<HEAD>
<TITLE>ASP Page for the Dictionary Object Example</TITLE>
</HEAD>
<BODY>

            <% Show Greeting %>

<SCRIPT LANGUAGE="VBScript" RUNAT="Server">

Sub ShowGreeting(  )
   Dim StateDict
   Dim ClientName, ClientState

   ' Initialize dictionary
Set StateDict = Server.CreateObject("Scripting.Dictionary")
StateDict.Add "NY", "New York"
StateDict.Add "CA", "California"
StateDict.Add "FL", "Florida"
StateDict.Add "WA", "Washington"
StateDict.Add "MI", "Michigan"
StateDict.Add "MA", "Massachusetts"
StateDict.Add "MN", "Minnesota"
' add other states

ClientName = Server.HTMLEncode(Request.Form("VisitorName"))
ClientState = Server.HTMLEncode(Request.Form("State"))

Response.Write("Hello, " & ClientName & ". <P>")
Response.Write("We are pleased to have a visitor from ")
   Response.Write(StateDict.Item(ClientState) & "!")
End Sub
</SCRIPT>
</BODY>
</HTML>
 
Méthode Dictionary.Items  
 
 
Syntaxe
dictionaryobject.Items
dictionaryobject

Utilisation : Obligatoire

Type de données : Objet Dictionary

Une référence à un objet Dictionary.

 
Valeur renvoyée

Une table Variante.

 
Description

Renvoie une table contenant tous les éléments de l'objet Dictionary spécifié.

 
Les règles en bref

La table renvoyée représente toujours une table variante basée sur zéro dont le type de données correspond à celui des éléments de l'objet Dictionary.

 
Conseils de programmation et pièges
  • Le seul moyen d'accéder directement aux membres de l'objet Dictionary est de passer par les valeurs clés. Cependant, grâce à la méthode Items, vous pouvez "vider" les données de l'objet Dictionary dans une table variante à base zéro. Il est ainsi possible d'accéder normalement aux éléments de données comme s'il s'agissait d'une table, comme le montre le code suivant :

    Dim vArray
    vArray = DictObj.Items
    For i = 0 to DictObj.Count -1
        Response.Write vArray(i) & "<P>"
    Next I
  • La méthode Items récupère uniquement les éléments stockés dans un objet Dictionary ; vous pouvez récupérer toutes les clés de l'objet Dictionary en appelant la méthode Keys qui lui est associée.

 
Voir aussi

Méthode Dictionary.Keys

 
Propriété Dictionary.Key  
 
 
Syntaxe
dictionaryobject.Key(key) = newkey
dictionaryobject

Utilisation : Obligatoire

Type de données : Objet Dictionary

Une référence à un objet Dictionary.

key

Utilisation : Obligatoire

Type de données : Chaîne

La clé d'un élément de dictionnaire existant.

newkey

Utilisation : Obligatoire

Type de données : Chaîne

Une nouvelle clé unique pour cet élément de dictionnaire.

 
Type de données

Une chaîne.

 
Description

Remplace une clé existante par une nouvelle clé.

 
Les règles en bref
  • La propriété Key est une propriété en écriture seule.

  • key, la valeur clé existante, doit figurer dans le dictionnaire sous peine de générer une erreur.

  • La valeur newkey doit être unique et ne doit pas déjà figurer dans le dictionnaire sous peine de générer une erreur.

  • La comparaison des valeurs key et newkey avec les valeurs clés existantes est définie par la propriété CompareMode de l'objet Dictionary.

 
Exemple
Private Function ChangeKeyValue(sOldKey, sNewKey)
'Assumes oDictionary is a public object
    If oDictionary.Exists(sOldKey) Then
        oDictionary.Key(sOldKey) = sNewKey
        ChangeKeyValue = True
    Else
        ChangeKeyValue = False
    End If
End Function
 
Conseils de programmation et pièges
  • Utilisez la propriété Key pour modifier le nom d'une clé existante. Utilisez la méthode Add pour ajouter une nouvelle clé et la valeur qui lui est associée à l'objet Dictionary. Utilisez la méthode Keys pour récupérer les noms de toutes les clés ; cette méthode est particulièrement utile lorsque vous ne connaissez pas au préalable les noms ni les contenus du dictionnaire.

  • Toute tentative de récupération d'un nom de clé (une opération absurde puisque cela revient à indiquer le nom de la clé en vue de récupérer ce même nom) génère une erreur ; il en est de même pour toute tentative de modification d'un nom de clé qui n'a pas encore été ajouté au dictionnaire.

  • Utiliser une boucle For Each...Next pour itérer les membres d'un objet Dictionary implique un appel tacite de la propriété Key. En d'autres termes, chaque itération de la boucle renvoie une clé plutôt qu'un élément de données. Pour récupérer les données du membre, vous devez donc utiliser sa valeur clé pour accéder à ses données via la propriété Item. Comme le montre l'exemple de la propriété Dictionary.Item.

 
Méthode Dictionary.Keys  
 
 
Syntaxe
dictionaryobject.Keys
dictionaryobject

Utilisation : Obligatoire

Type de données : Objet Dictionary

Une référence à un objet Dictionary.

 
Valeur renvoyée

Une table de chaînes.

 
Description

Renvoie une table contenant toutes les valeurs Key de l'objet Dictionary spécifié.

 
Les règles en bref

La table renvoyée représente toujours une table variante à base zéro dont le type de données est String.

 
Conseils de programmation et pièges

La méthode Keys permet de récupérer uniquement les clés stockées dans un objet Dictionary. La méthode Items de l'objet Dictionary permet de récupérer tous les éléments de cet objet. La propriété Item de l'objet Dictionary permet de rappeler un élément de données particulier.

 
Exemple
Dim vArray
vArray = DictObj.Keys
For i = 0 to DictObj.Count -1
    Response.Write vArray(i) & "<BR>"
Next
 
Méthode Dictionary.Remove  
 
 
Syntaxe
dictionaryobject.Remove key
dictionaryobject

Utilisation : Obligatoire

Type de données : Objet Dictionary

Une référence à un objet Dictionary.

key

Utilisation : Obligatoire

Type de données : Chaîne

La clé associée à l'élément à supprimer.

 
Description

Supprime aussi bien la clé spécifiée que les données qui lui sont associées (à savoir, son élément) du dictionnaire.

 
Les règles en bref

Si la valeur key n'existe pas, une erreur d'exécution 32811, "Elément introuvable," s'affiche.

 
Méthode Dictionary.RemoveAll  
 
 
Syntaxe
dictionaryobject.RemoveAll
dictionaryobject

Utilisation : Obligatoire

Type de données : Objet Dictionary

Une référence à un objet Dictionary.

 
Description

Efface le dictionnaire ; en d'autres termes, supprime toutes les clés et les données qui leur sont associées du dictionnaire.

 
Conseils de programmation et pièges

Si vous voulez supprimer un nombre donné de membres plutôt que la totalité des contenus du dictionnaire, utilisez la méthode Remove.