The julia language has quite a few functions to show information about an object to the user. While the output is often similar, it is not exactly the same with each of these methods. The official documentation is still missing a cohesive description of I/O functions, so I went through some of the julia base source code trying to understand the differences. Here is my current understanding:
Which function is used for what?
display
is meant for interactive use and is Display aware. This means, that depending on whether a REPL or an IJulia notebook is used to evaluate the code, this output will vary. For example, the REPL display of an image may yield an instructive description of the object – including the type of the object and its identifying fields – while the Notebook output may yield an actual picture. When a function is called interactively, its return value isdisplay
ed.print
is meant for non-interactive use, generating output programatically. It is thus the basis ofprintln
, etc. and yields an undecorated string representation. Undecorated here means that no julia-specific type info is included. E.g. while thedisplay
of an array may output1232-element Array{Float64,1}:1.02.0print
1[1.0, 2.0]dump
is meant for inspection. It will yield the most elaborate description of an object and, recursively, its fields, etc. This function is typically not called in everyday use.
Which function should I override for my custom types?
This is where the function show
comes in. In fact all displaying functions apart from dump
rely on show
under the hood. Note, that we probably don’t need to override dump
anyways as we don’t want to deviate from the default behavior of showing all available information.
So for our custom types we can
- override
show(io,x)
with the undecorated form for print. - override
show(io,mime::MIME...,x)
with the most useful interactive output with a given multimedia capability (MIME…). E.g. for the REPL version usemime::MIME"text/plain"
. This will be used for display.
Should you nonetheless need to override dump
, then dump(io,x,maxdepth=8,indent="")
is what you should be defining.
Where is this documented?
Of course relying on implementational details instead of published documentation is a risky business, as these things tend to change over time. As stated above, I wasn’t able to find such documentation in the official docs. However, the understanding described above is consistent with this section from the docs:
Just as text output is performed by print and user-defined types can indicate their textual representation by overloading show, Julia provides a standardized mechanism for rich multimedia output (such as images, formatted text, or even audio and video) […]: – A function display(x) to request the richest available multimedia display of a Julia object x (with a plain-text fallback). – Overloading show allows one to indicate arbitrary multimedia representations (keyed by standard MIME types) of user-defined types. […] The base Julia runtime provides only plain-text display, but richer displays may be enabled by loading external modules or by using graphical Julia environments (such as the IPython-based IJulia notebook).