.. _dictionary:

###################
  ROOT Dictionaries
###################

This section is a follow-up to :ref:`data-reduction`. In that
exercise, we used a dictionary and a file that were created by someone
else. [#byme]_

While I was preparing a project that was going to do some advanced
ROOT I/O, I set up some test programs to teach myself how
dictionaries worked in the latest versions of ROOT. After I finished
my tests, it occurred to me that they might be useful in the ROOT
tutorial, at least as a reference.

Make no mistake, this is fairly advanced ROOT work. I can't imagine
someone being asked to create a ROOT file with complex structure
elements as part of a summer project. However, as I said in
:ref:`data-reduction`, it's possible that you may be asked to read a
file with such structures. That's why I've only included examples of
*creating* a file using a dictionary in C++, but have examples of
*reading* a such a file in both C++ and Python.

To keep this discussion relatively short, I'm going to assume that
you've at least skimmed :ref:`containers` and :ref:`data-reduction`;
in other words, that you've been introduced to the idea of `vectors
<https://www.geeksforgeeks.org/vector-in-cpp-stl/>`_ and creating
`TTrees <https://root.cern/doc/master/classTTree.html>`_.

   
.. toctree::
   :maxdepth: 1
   
   WhyDictionary.md
   Interpreter.md
   Compiled.md


.. admonition:: These pages are incomplete
   
   As you look through the `example files
   <https://www.nevis.columbia.edu/~seligman/root-class/files/root-dict/>`_,
   you'll see that the code files (ending in `.h`, `.cxx`, and `.py`) contain
   lots of comments. The web discussion in the following pages
   supplements those comments, but does not replace them.

   In other words, this appendix mostly discusses "why". It's the code
   that describes "how".


.. figure:: https://imgs.xkcd.com/comics/five_word_jargon.png
   :align: center
   :width: 50 %

   https://xkcd.com/2326/ by Randall Munroe. You never know when a dictionary might be useful. 

.. rubric:: Footnotes

.. [#byme] OK, that "someone else" was me. But you get the idea.