Navigation: Macros > Macro Language > Built-in Functions > All Functions

List_Add

str = List_Add(sListVarName, sSomeText, nSomeNumber)

This macro function is used to add a string and/or an number to an existing list.

In the image, on the right, the various parts of a list are shown.

•Each element of a list contains a string and, optionally, a number.

•If the string contains an equal sign (=), then it is possible to access the text on the left as the "name" and the text on the right as the "value".

Consider the macro code below, which adds some entries to a list and then calls various list functions to get back some information.

List_Clear(sListCountries)
// put some values in the list
List_Add(sListCountries, 'Egypt=Ägypten', 10133)     // item 1
List_Add(sListCountries, 'Albania=Albanien', 10165)  // item 2
List_Add(sListCountries, 'Algeria=Algerien', 10183)  // item 3
List_Add(sListCountries, 'Andorra=Andorra', 10167)   // item 4
List_Add(sListCountries, 'Armenia=Armenien', 10180)  // item 5
// now get some information back from the list
sResult = List_GetName(sListCountries, 4) // 'Andorra'
nResult = List_GetNumber(sListCountries, 1) // 10133
sResult = List_GetValue(sListCountries, 5) // 'Armenien'
sResult = List_GetString(sListCountries, 3) // 'Algeria=Algerien'

The more complex macro code, below, uses an override list of country names to replace the country names in the holidays table (this could be a bespoke list of country names, or the translation of country names into a different language). If no override name is found, then the default name from the table is used to build a list with all the overridden, or not, country names and their holidays set ID from the table.

// load the list of country names override
List_LoadFromFile(sListCountryNameOverrides, sFileCountryNames, true)
List_Sort(sListCountryNameOverrides)
List_RemoveDuplicates(sListCountryNameOverrides)
nNumCountryOverrides = List_Count(sListCountryNameOverrides)
// make sure the list to be filled is empty
List_Clear(sListCountries)
// loop over the sets in the a-holidays
nSetIndexPos = 1
nSetID = GetNthHolSetId('a', nSetIndexPos)
while nSetID <> 0
    // only look for override if there are any overrides at all
    if nNumCountryOverrides > 0
        nIdxOverride = List_LocateName(sListCountryNameOverrides, IntToStr(nSetID))
     else
         nIdxOverride = 0
     endif
     // if an override name is found, then use it
    if nIdxOverride > 0
        sCurSetName = List_GetValue(sListCountryNameOverrides, nIdxOverride)
    else
        // otherwise use the deafult name in the table
        sCurSetName = GetHolSetNameOfId()
    endif
    // add the name found above to the new mixed list of country names
    List_Add(sListCountries, sCurSetName, nSetID)
    // move to next SET of the LIST
    nSetIndexPos = nSetIndexPos + 1
    nSetID = GetNthHolSetId(sCurHolList, nSetIndexPos)
endwhile
List_Sort(sListCountries)

// now work with this list of overriden country names
// ...

When using lists, don't forget to always use the function List_Create to create your list at the top of the macro, and then the function List_Destroy to destroy it at the end of the macro.

Please enable JavaScript to view this site.

List_Add