ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

Help / WLanguage / WLanguage syntax / Declaring variables
  • Accessing the associative arrays
  • Accessing the elements of the associative arrays
  • How to initialize an associative array as soon as it is declared?
  • Browsing the associative arrays
  • WLanguage functions and arrays
  • Associative Array parameters
  • Associative array of classes or structures
  • Associative array of arrays, queue, stack, list
WINDEV
WindowsLinuxUniversal Windows 10 AppJavaReports and QueriesUser code (UMC)
WEBDEV
WindowsLinuxPHPWEBDEV - Browser code
WINDEV Mobile
AndroidAndroid Widget iPhone/iPadIOS WidgetApple WatchMac CatalystUniversal Windows 10 App
Others
Stored procedures
Associative array (Variable type)
In french: Tableau associatif
An associative array is an "advanced" type of array: it is used to group a set of elements of the same type. Each element of the array is indexed on any type of information (and not simply on a numeric index, as in the other types of arrays).
Remark: This type of array allows you to quickly access any element, with some options on the strings.
Example
// Fills an associative array with the sizes of files
aaFileSize is associative array of int
aaFileSize["File1.txt"] = fSize("File1.txt")
aaFileSize["File2.txt"] = fSize("File2.txt")

// Retrieves the size of a file
Trace(aaFileSize["File2.txt"])

// Iterates over file sizes
sFile is string
nSize is int

// sFile is used to get the search key of the associative array
FOR EACH ELEMENT nSize,sFile OF aaFileSize
	Trace(StringBuild("%1: %2", sFile, nSize)) 
END
Syntax

Declaring an associative array Hide the details

<Array name> is associative array [(<Options> [, <Default value> [, <Key type> [, <Initial size>]]])] of <Type>
<Array name>:
Name of the array variable to declare.
<Options>:
Combination of constants used to configure the operating mode of the array:
WithDuplicatesThis constant is used to allow the duplicates. By default, an associative array cannot contain any duplicates.
ccIgnoreAccentIf the type of key is a string (by default), the indexing ignores the accented characters.
ccIgnoreCaseIf the type of key is a string (by default), the indexing is not case sensitive.
ccIgnoreSpaceIf the type of key is a string (by default), the indexing ignores the space characters.
ccIgnorePunctuationAndSpaceIf the type of key is a string (by default), the indexing is not punctuation sensitive and it ignores the space characters.
WithoutDuplicates (default)By default, an associative array cannot contain any duplicates.
You can leave this constant unspecified.
The "*" value allows you to keep the default value of the option.
<Default value>:
Value returned when accessing a non-existing element in an associative array without duplicate. This parameter is ignored in an associative array with duplicates. The default value defined for the array's type is used by default (0, "", False).
The "*" value is used to keep the default value of the type.
<Key type>:
Type of the key used to browse the array. By default, the browse operation is performed in a string key. The authorized types are as follows:
wlStringCharacter string
wlUnicodeStringUnicode string
wlDateDate
wlDateTimeDateTime
wlIntSigned 4-byte integer
wlInt_8Signed 8-byte integer
wlUnsignedInt_4Unsigned 4-byte integer
wlUnsignedInt_8Unsigned 8-byte integer
wlTimeTime
wlCurrencyCurrency
wlNumericNumeric
wlReal8-byte real
The "*" value is used to keep the default key type (string).
<Initial size>:
Integer. Corresponds to the initial size of the memory area for the associative array.
The addition in an associative array may be quite long if the array is resized. In case of multiple additions, we recommend that you oversize the array in order to optimize the additions.
The "*" value allows you to keep the default size.
<Type>:
Type of the elements in the array.
Universal Windows 10 AppiPhone/iPadIOS WidgetApple WatchMac Catalyst Remark: The elements that make up the array can also be arrays, fixed arrays, associative arrays, queues, stacks or lists.

Declaring an associative array parameter Hide the details

<Parameter name> is associative array of <Type>
<Parameter name>:
Name of the array variable to declare.
<Type>:
Type of the elements in the array.
Universal Windows 10 AppiPhone/iPadIOS WidgetApple WatchMac Catalyst Remark: The elements that make up the array can also be arrays, fixed arrays, associative arrays, queues, stacks or lists.
Remarks

Accessing the associative arrays

The following properties can be used to handle an associative array:
CountReturns the number of occurrences in the array.
EmptyUsed to find out whether the array is empty or not.
The &Array and Array1 = Array2 syntaxes are not allowed. Associative arrays do not allow for reference operators or copying.

Accessing the elements of the associative arrays

The access to the elements found in an associative array differs depending on whether the associative array accepts duplicates or not.
Associative array without duplicates
Exist property
MyArray[MyKey]..Exist

Returns True if the MyKey element exists, False otherwise.
AndroidAndroid Widget Property not available.
Empty property
MyArray[MyKey]..Empty

Returns True if the MyKey element does not exist, False otherwise.
Count property
MyArray[MyKey]..Occurence

Returns 1 if the MyKey element exists, 0 if the element does not exist.
Assigning an element
MyArray[MyKey] = <Value>

If the MyKey element does not exist, a MyKey element is created and assigned with <Value>.
If the MyKey element exists, its value is modified.
MyArray[MyKey, Index] = Value

A WLanguage error occurs if the index is different from 1.
A WLanguage error occurs if the MyKey element does not exist.
If the MyKey element exists, its value is modified.

Syntax compatible with the associative arrays with duplicates.
MyArray[MyKey]++

Creates the entry in the associative array, with the default value specified when declaring the array.
Access to element
MyArray[MyKey]

If the MyKey element does not exist, returns the default value of the array.
If the MyKey element exists, returns the value of the element.
MyArray[MyKey, Index]

A WLanguage error occurs if the index is different from 1.
A WLanguage error occurs if the MyKey element does not exist.
If the MyKey element exists, returns the value of the element.

Syntax compatible with the associative arrays with duplicates.
Address of element
&MyArray[MyKey]

A WLanguage error occurs if the MyKey element does not exist.
If the MyKey element exists, returns the address of the element.
&MyArray[MyKey, Index]

A WLanguage error occurs if the index is different from 1.
A WLanguage error occurs if the MyKey element does not exist.
If the MyKey element exists, returns the address of the element.

Syntax compatible with the associative arrays with duplicates.
Associative array with duplicates
Exist property
MyArray[MyKey]..Exist

Returns True if at least one MyKey element exists, False if the MyKey element does not exist.
AndroidAndroid Widget Property not available.
Checking the existence of a key: Empty property
MyArray[MyKey]..Empty

Returns True if the MyKey element does not exist, False if there is at least one MyKey element.
Number of elements found in a key: Count property
MyArray[MyKey]..Occurence

Returns the number of MyKey elements.
Assigning an element
MyArray[MyKey] = <Value>

Creates a MyKey element and assigns the specified value to this element (even if MyKey elements already exist).
MyArray[MyKey, Index] = Value

A WLanguage error occurs if the index is greater than the number of existing elements.
A WLanguage error occurs if the MyKey element does not exist.
If the MyKey element exists, the value of the element identified by its index is modified.
Access to element
MyArray[MyKey]

Invalid syntax that triggers a WLanguage error (because several elements can correspond to the same key).
MyArray[MyKey, Index]

A WLanguage error occurs if the index is greater than the number of existing elements.
A WLanguage error occurs if the MyKey element does not exist.
If the MyKey element exists, returns the value of the element identified by its index.
Address of element
&MyArray[MyKey]

Syntax not allowed
&MyArray[MyKey, Index]

A WLanguage error occurs if the index is greater than the number of existing elements.
A WLanguage error occurs if the MyKey element does not exist.
If the MyKey element exists, returns the address of the element identified by its index.

You have the ability to use the multiple assignment for the associative arrays.

How to initialize an associative array as soon as it is declared?

To initialize an associative array as soon as it is declared, all you have to do is add the "key/value" couples by using the [ ] operator (square brackets). The syntax is as follows:
aaMyArray is associative array of xxx = ...
[ [<key1>, <value1>], [<key2>, <value2>], ... ]

For example:
// Stores the VAT rates by name
aaVATRate is associative array of real = ...
	[["Normal", 0.2], ["Intermediate", 0.1], ["Low", 0.055]]

Browsing the associative arrays

The elements of an associative array can be browsed by using the FOR EACH syntax specific to the associative arrays.

WLanguage functions and arrays

Several WLanguage functions can be used to handle the associative arrays. For more details, see Array functions.
This allows you to delete an element from an associative array by using Delete (or ArrayDelete) via the following syntax:
Delete(ArrayName, key)
ArrayDelete(ArrayName, Key)

Associative Array parameters

  • The type of elements found in the associative array passed as parameter must be the same as the declaration type.
  • An associative array cannot be passed by value. A variable must necessarily be passed as parameter.
    Example:
    // Adds a customer into the array
    PROCEDURE AddCustomer(aaCustomer is associative array of CCustomer,
    	sName is string,
    	sInfo is string)
    // Builds the new customer object
    c is CCustomer(sName, sInfo)
    // Adds the new object to the array
    aaCustomer[sName] = c
  • No check is performed during the compilation: checks are performed at runtime.
  • Associative arrays do not allow for reference operators or copying.

Associative array of classes or structures

If you are using an associative array of classes or structures, the different instances are automatically copied during the additions.
If you are using an associative array of dynamic classes or dynamic structures, the classes or the structures must e allocated during addition (the freeing operations are automatically performed).
Examples:
// Case of an array of non-dynamic objects
// Object
clObj is cLMyClass
// Associative array of objects
aaAssociative is associative array of cLMyClass
// Assign one of the object members
clObj:nMember = 0
// Add into the associative array. 
// It is an array of non-dynamic objects, therefore the object is copied
// The assignment can be quite "long" if there are a lot of members
aaAssociative["Association"] = clObj
// Change in the initial object
clObj:nMember = 2
// The object was copied, therefore 0 is found in the array 
// (value during the assignment)
Info(aaAssociative["Association"]:nMember)
// Case of an array of dynamic objects
// Dynamic object
pclObj is dynamic cLMyClass
// Associative array of dynamic objects
aaAssociative is associative array of dynamic cLMyClass
// Allocate a dynamic object
pclObj = new cLMyClass
// Assign one of the object members
pclObj:nMember = 0
// Add into the associative array. 
// It is an array of dynamic objects. 
// Therefore, it is a new "pointer" to the same object (fast assignment)
aaAssociative["Association"] = pclObj
// Change in the initial object
pclObj:nMember = 2
// The array contains the same object therefore 2 in the array as well
Info(aaAssociative["Association"]:nMember)
Accessing the members of a non-existing element in an associative array of structures or classes does not automatically create the instance of the structure or class.
The line of code:
MyAssociativeArray["Key"]:Member = 5
fails if the "Key" element was not created beforehand.
Universal Windows 10 AppiPhone/iPadIOS WidgetApple WatchMac Catalyst

Associative array of arrays, queue, stack, list

The following syntaxes are supported:
<variable> is associative array of arrays of int
<variable> is associative array (withDuplicates) of arrays of int
<variable> is associative array (withDuplicates,wlInt) of arrays of int
<variable> is associative array of arrays of 5 int
<variable> is associative array (withDuplicates) of arrays of 5 int
<variable> is associative array (withDuplicates,wlInt) of arrays of 5 integers

<variable> is associative array of fixed arrays of 5 int
<variable> is associative array (withDuplicates) of  fixed arrays of 5 int
<variable> is associative array (withDuplicates,wlInt) of fixed arrays of 5 int
<variable> is associative array of associative arrays of int
<variable> is associative array (withDuplicates) of associative arrays of int
<variable> is associative array (withDuplicates,wlInt) of associative arrays of int

<variable> is associative array of associative arrays (withDuplicates) of int
<variable> is associative array (withDuplicates) of associative arrays ...
(withDuplicates) of int
<variable> is associative array (withDuplicates,wlInt) of associative arrays ...
(withDuplicates) of int
<variable> is associative array of associative arrays ...
(withDuplicates,wlInt) of int
<variable> is associative array (withDuplicates) of associative arrays ...
(withDuplicates,wlInt) of int
<variable> is associative array (withDuplicates,wlInt) of associative arrays ...
(withDuplicates,wlInt) of int

<variable> is associative array of queue of int
<variable> is associative array (withDuplicates) of queue of int
<variable> is associative array (withDuplicates,wlInt) of queue of int

<variable> is associative array of lists of int
<variable> is associative array (withDuplicates) of stacks of integers
<variable> is associative array (withDuplicates,wlInt) of stacks of integers

<variable> is associative array of lists of int
<variable> is associative array (withDuplicates) of lists of int
<variable> is associative array (withDuplicates,wlInt) of lists of int
Example: Associative array of arrays of strings:
// Declaration
arrClasses is associative array of array <growth> of strings

// Inserts an element into the associative array 
Insert(arrClasses, "CM2")

// Fill the CM2 student
arrClasses["CM2"][1] = "ALARD Stephen"
arrClasses["CM2"][2] = "BERTAU Kevin"

// Inserts an element into the associative array 
Insert(arrClasses, "CM1")

// Fill the CM1 student
arrClasses["CM1"][1] = "ALONSO Bernie"
arrClasses["CM1"][2] = "CRISTO Benjie"

FOR EACH AClass, sName of arrClasses
	FOR EACH Student OF AClass
		Trace(sName + ":" + Student)
	END
END
Related Examples:
The associative arrays Unit examples (WINDEV): The associative arrays
[ + ] Using the associative arrays of WLanguage:
- Fill an associative array
- Access an associative array
Minimum version required
  • Version 11
This page is also available for…
Comments
Also called a dictionary
An associative Array is also know as a dictionary, for example in Python.
Sebastian
02 Jun. 2015

Last update: 04/11/2024

Send a report | Local help