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.