dict

Выполняет одну из нескольких операций со значениями словарей или переменными, содержащими значения словарей (см. раздел ЗНАЧЕНИЯ СЛОВАРЯ ниже для описания), в зависимости от опции. Допустимые опции (которые можно сократить) включают:

dict append dictionaryVariable key ?string ...?

Это добавляет заданную строку (или строки) к значению, которому сопоставлен данный ключ в словаре, содержащемся в заданной переменной, записывая полученное значение словаря обратно в эту переменную. Отсутствующие ключи обрабатываются так, как если бы они отображались на пустую строку. Обновленное значение словаря возвращается.

dict create ?key value ...?

Возвращает новый словарь, содержащий каждое из сопоставлений ключ/значение, перечисленных в качестве аргументов (ключи и значения чередуются, причем каждый ключ следует за его сопоставленным значением).

dict exists dictionaryValue key ?key ...?

Это возвращает булево значение, указывающее, существует ли заданный ключ (или путь ключей через набор вложенных словарей) в данном значении словаря. Это возвращает истинное значение ровно тогда, когда dict get по этому пути будет успешным.

dict filter dictionaryValue filterType arg ?arg ...?

Это принимает значение словаря и возвращает новый словарь, содержащий только те пары ключ/значение, которые соответствуют указанному типу фильтра (который может быть сокращен). Поддерживаемые типы фильтров:

dict filter dictionaryValue key ?globPattern ...?: Правило ключа соответствует только тем парам ключ/значение, ключи которых соответствуют любому из заданных шаблонов (в стиле string match).
dict filter dictionaryValue script {keyVariable valueVariable} script: Правило скрипта проверяет соответствие, присваивая ключ переменной keyVariable, а значение — переменной valueVariable, а затем оценивая заданный скрипт, который должен возвращать булево значение (пара ключ/значение включается только в результат dict filter, когда возвращается истинное значение). Обратите внимание, что первый аргумент после слова выбора правила — список из двух элементов. Если скрипт возвращает условие TCL_BREAK, никакие другие пары ключ/значение не рассматриваются для включения в результирующий словарь, а условие TCL_CONTINUE эквивалентно ложному результату. Пары ключ/значение проверяются в том порядке, в котором ключи были вставлены в словарь.
dict filter dictionaryValue value ?globPattern ...?: Правило значения соответствует только тем парам ключ/значение, значения которых соответствуют любому из заданных шаблонов (в стиле string match).

dict for {keyVariable valueVariable} dictionaryValue body

Эта команда принимает три аргумента: первый — список из двух имён переменных (для ключа и значения соответственно каждого сопоставления в словаре), второй — значение словаря, по которому будет происходить итерация, и третий — скрипт, который будет вычисляться для каждого сопоставления с соответствующим образом установленными переменными ключа и значения (подобно команде foreach). Результатом команды является пустая строка. Если какое-либо вычисление тела генерирует результат TCL_BREAK, никакие другие пары из словаря не будут обрабатываться, и команда dict for завершится успешно немедленно. Если какое-либо вычисление тела генерирует результат TCL_CONTINUE, это будет рассматриваться точно так же, как и обычный результат TCL_OK. Порядок итерации — порядок, в котором ключи были вставлены в словарь.

dict get dictionaryValue ?key ...?

Принимая значение словаря (первый аргумент) и ключ (второй аргумент), это извлечёт значение для этого ключа. Если указано несколько ключей, поведение команды будет таким, как если бы результат dict get $dictVal $key был передан в качестве первого аргумента в dict get, а оставшиеся аргументы — как второй (и, возможно, последующие) аргументы. Это облегчает поиск во вложенных словарях. Например, следующие две команды эквивалентны:

dict get $dict foo bar spong
dict get [dict get [dict get $dict foo] bar] spong

Если ключи не указаны, dict get вернёт список, содержащий пары элементов, аналогично array get. То есть первый элемент каждой пары — ключ, а второй — значение для этого ключа.

Попытка получить значение для ключа, отсутствующего в словаре, является ошибкой.

dict incr dictionaryVariable key ?increment?

Это добавляет заданное значение приращения (целое число, по умолчанию 1, если не указано) к значению, которому сопоставлен данный ключ в значении словаря, содержащемся в заданной переменной, записывая результирующее значение словаря обратно в эту переменную. Отсутствующие ключи обрабатываются так, как если бы они отображались на 0. Попытка инкрементировать значение существующего ключа, если это значение не является целым числом, является ошибкой. Обновленное значение словаря возвращается.

dict info dictionaryValue

Возвращает информацию (предназначенную для отображения пользователям) о данном словаре, хотя формат этой информации зависит от реализации словаря. Для словарей, реализованных с помощью хеш-таблиц, ожидается, что это вернёт строку, полученную из Tcl_HashStats, аналогично array statistics.

dict keys dictionaryValue ?globPattern?

Возвращает список всех ключей в данном значении словаря. Если указан шаблон, возвращаются только те ключи, которые ему соответствуют (согласно правилам string match). Возвращаемые ключи будут в порядке, в котором они были вставлены в словарь.

dict lappend dictionaryVariable key ?value ...?

Добавляет указанные элементы к списку значений, которому сопоставлен данный ключ в значении словаря, содержащемся в заданной переменной, записывая результирующее значение словаря обратно в эту переменную. Отсутствующие ключи обрабатываются так, как если бы они отображались на пустой список, и допускается отсутствие элементов для добавления в список. Недопустимо, чтобы значение, которому сопоставлен ключ, не представляло собой список. Обновленное значение словаря возвращается.

dict map {keyVariable valueVariable} dictionaryValue body

Эта команда применяет преобразование к каждому элементу словаря, возвращая новый словарь. Она принимает три аргумента: первый — список из двух имён переменных (для ключа и значения соответственно каждого сопоставления в словаре), второй — значение словаря, по которому будет происходить итерация, и третий — скрипт, который будет вычисляться для каждого сопоставления с соответствующим образом установленными переменными ключа и значения (подобно lmap). В случае успешного завершения вычислений скрипта (TCL_OK, в отличие от ошибки и т. д.) результат скрипта помещается в накопительный словарь с ключом, который является текущим содержимым переменной keyVariable в этот момент. Результатом команды dict map является накопительный словарь после обработки всех ключей.

Если вычисление тела для любого определённого шага генерирует break, никакие другие пары из словаря не будут обрабатываться, и команда dict map завершится успешно немедленно. Если вычисление тела для определённого шага генерирует результат continue, текущая итерация прерывается, и накопительный словарь не изменяется. Порядок итерации — естественный порядок словаря (как правило, порядок, в котором ключи были добавлены в словарь; порядок такой же, как и в dict for).

dict merge ?dictionaryValue ...?

Возвращает словарь, содержащий содержимое каждого из аргументов dictionaryValue. В случае, если два (или более) словаря содержат сопоставление для одного и того же ключа, результирующий словарь сопоставляет этот ключ со значением в соответствии с последним словарем в командной строке, содержащим сопоставление для этого ключа.

dict remove dictionaryValue ?key ...?

Возвращает новый словарь, являющийся копией старого, переданного в качестве первого аргумента, за исключением сопоставлений для каждого из перечисленных ключей. Разрешается отсутствие ключей для удаления, а также любой из ключей для удаления может отсутствовать в исходном словаре.

dict replace dictionaryValue ?key value ...?

Возвращает новый словарь, являющийся копией старого, переданного в качестве первого аргумента, за исключением некоторых отличающихся значений или добавленных пар ключ/значение. Допускается вызов этой команды без пар ключ/значение, но запрещается вызов с ключом без значения.

dict set dictionaryVariable key ?key ...? value

Эта операция принимает имя переменной, содержащей значение словаря, и помещает обновлённое значение словаря в эту переменную, содержащее сопоставление заданного ключа с заданным значением. При наличии нескольких ключей эта операция создаёт или обновляет цепочку вложенных словарей. Обновлённое значение словаря возвращается.

dict size dictionaryValue

Возвращает количество пар ключ/значение в данном значении словаря.

dict unset dictionaryVariable key ?key ...?

Эта операция (партнёр dict set) принимает имя переменной, содержащей значение словаря, и помещает обновлённое значение словаря в эту переменную, не содержащее сопоставления для данного ключа. При наличии нескольких ключей это описывает путь через вложенные словари к сопоставлению для удаления. Необходимо указать хотя бы один ключ, но последний ключ на пути ключей не обязательно должен существовать. Все остальные компоненты на пути должны существовать. Обновлённое значение словаря возвращается.

dict update dictionaryVariable key varName ?key varName ...? body

Выполните скрипт Tcl в body со значением для каждого key (найденного при чтении значения словаря в dictionaryVariable), сопоставленным переменной varName. Может быть несколько пар key/varName. Если у key нет сопоставления, это соответствует не заданной varName. По завершении body, любые изменения, внесенные в varName, отражаются обратно в словарь в dictionaryVariable (если сам dictionaryVariable не становится недоступным, в этом случае все обновления отбрасываются молча), даже если результат body — ошибка или другой тип исключительного выхода. Результат команды dict update — (если не происходит ошибка) результат вычисления body.

Каждая varName сопоставляется в области, охватывающей dict update; рекомендуется использовать эту команду только в локальной области (процедура proc, лямбда-выражение для apply или метод). Из-за этого переменные, заданные dict update, будут продолжать существовать после завершения команды (если их явно не unset). Обратите внимание, что сопоставление значений с переменными не использует отслеживание; изменения содержимого dictionaryVariable происходят только по завершении body.

dict values dictionaryValue ?globPattern?

Возвращает список всех значений в заданном значении словаря. Если указан шаблон, будут возвращены только те значения, которые ему соответствуют (согласно правилам string match). Возвращаемые значения будут в том порядке, в котором ключи, связанные с этими значениями, были добавлены в словарь.

dict with dictionaryVariable ?key ...? body

Выполняет скрипт Tcl в body со значением для каждого ключа в dictionaryVariable, сопоставленным (аналогично dict update) переменной с тем же именем. Если доступно одно или несколько key, это указывает на цепочку вложенных словарей, при этом внутренний словарь открывается для выполнения body. Как и в случае с dict update, если dictionaryVariable становится недоступным, обновления словаря отбрасываются, и это также происходит, если содержимое dictionaryVariable изменяется так, что цепочка словарей больше не существует. Результат dict with — (если не происходит ошибка) результат вычисления body.

Переменные сопоставляются в области, охватывающей dict with; рекомендуется использовать эту команду только в локальной области (процедура proc, лямбда-выражение для apply или метод). Из-за этого переменные, заданные dict with, будут продолжать существовать после завершения команды (если их явно не unset). Обратите внимание, что сопоставление значений с переменными не использует отслеживание; изменения содержимого dictionaryVariable происходят только по завершении body.

Если dictionaryVariable содержит значение, которое не является словарем в момент завершения body (что может легко произойти, если имя совпадает с любым из ключей в словаре), в этот момент возникает ошибка. Поэтому данная команда не рекомендуется для использования, когда ожидается, что ключи в словаре будут совпадать с именем переменной dictionaryVariable. Если содержимое ключа отображается на словарь, то чистый результат — объединение этого внутреннего словаря во внешний; см. ПРИМЕРЫ ниже для иллюстрации этого.

Значения словарей

Словари — это значения, содержащие эффективное, сохраняющее порядок отображение произвольных ключей на произвольные значения. Каждый ключ в словаре отображается на единственное значение. Они имеют текстовый формат, точно такой же, как любой список с чётным числом элементов, где каждое отображение в словаре представлено двумя элементами в списке. Когда команда принимает словарь и генерирует новый словарь на его основе (либо возвращает его, либо записывает его обратно в переменную, из которой читался исходный словарь), новый словарь будет иметь тот же порядок ключей, за исключением удалённых ключей и новых ключей, добавленных в конец. Когда строка интерпретируется как словарь, и у неё иначе бы были дублирующие ключи, используется только последнее значение для определённого ключа; остальные игнорируются, что означает, что «яблоко банан» и «яблоко морковь яблоко банан» — эквивалентные словари (с различными строковыми представлениями).

Операции, которые выводят новый словарь из старого (например, обновления типа dict set и dict unset), сохраняют порядок ключей в словаре. Исключением являются любые новые ключи, которые они добавляют, которые добавляются в последовательность, и любые ключи, которые удаляются, которые удаляются из порядка.

Примеры

Базовое использование словарей:

# Make a dictionary to map extensions to descriptions
set filetypes [dict create .txt "Text File" .tcl "Tcl File"]

# Add/update the dictionary
dict set filetypes .tcl "Tcl Script"
dict set filetypes .tm  "Tcl Module"
dict set filetypes .gif "GIF Image"
dict set filetypes .png "PNG Image"

# Simple read from the dictionary
set ext ".tcl"
set desc [dict get $filetypes $ext]
puts "$ext is for a $desc"

# Somewhat more complex, with existence test
foreach filename [glob *] {
    set ext [file extension $filename]
    if {[dict exists $filetypes $ext]} {
        puts "$filename is a [dict get $filetypes $ext]"
    }
}

Создание и использование вложенных словарей:

# Data for one employee
dict set employeeInfo 12345-A forenames "Joe"
dict set employeeInfo 12345-A surname   "Schmoe"
dict set employeeInfo 12345-A street "147 Short Street"
dict set employeeInfo 12345-A city   "Springfield"
dict set employeeInfo 12345-A phone  "555-1234"
# Data for another employee
dict set employeeInfo 98372-J forenames "Anne"
dict set employeeInfo 98372-J surname   "Other"
dict set employeeInfo 98372-J street "32995 Oakdale Way"
dict set employeeInfo 98372-J city   "Springfield"
dict set employeeInfo 98372-J phone  "555-8765"
# The above data probably ought to come from a database...

# Print out some employee info
set i 0
puts "There are [dict size $employeeInfo] employees"
dict for {id info} $employeeInfo {
    puts "Employee #[incr i]: $id"
    dict with info {
        puts "   Name: $forenames $surname"
        puts "   Address: $street, $city"
        puts "   Telephone: $phone"
    }
}
# Another way to iterate and pick out names...
foreach id [dict keys $employeeInfo] {
    puts "Hello, [dict get $employeeInfo $id forenames]!"
}

Локализованная версия string toupper:

# Set up the basic C locale
set capital [dict create C [dict create]]
foreach c [split {abcdefghijklmnopqrstuvwxyz} ""] {
    dict set capital C $c [string toupper $c]
}

# English locales can luckily share the "C" locale
dict set capital en [dict get $capital C]
dict set capital en_US [dict get $capital C]
dict set capital en_GB [dict get $capital C]

# ... and so on for other supported languages ...

# Now get the mapping for the current locale and use it.
set upperCaseMap [dict get $capital $env(LANG)]
set upperCase [string map $upperCaseMap $string]

Показ деталей dict with:

proc sumDictionary {varName} {
    upvar 1 $varName vbl
    foreach key [dict keys $vbl] {
        # Manufacture an entry in the subdictionary
        dict set vbl $key total 0
        # Add the values and remove the old
        dict with vbl $key {
            set total [expr {$x + $y + $z}]
            unset x y z
        }
    }
    puts "last total was $total, for key $key"
}

set myDict {
    a {x 1 y 2 z 3}
    b {x 6 y 5 z 4}
}

sumDictionary myDict
#    prints: last total was 15, for key b

puts "dictionary is now \"$myDict\""
#    prints: dictionary is now "a {total 6} b {total 15}"

При использовании dict with с ключом, совпадающим с именем переменной словаря:

set foo {foo {a b} bar 2 baz 3}
dict with foo {}
puts $foo
#    prints: a b foo {a b} bar 2 baz 3

См. также

append, array, foreach, mapeach, incr, list, lappend, set

Licensed under Tcl/Tk terms
https://www.tcl.tk/man/tcl/TclCmd/dict.htm