What is your favorite undocumented function?
What is your favorite undocumented function?
Warning: It' s not recommended to use undocumented internal functions as their definitions (and behavior) might change from version to version, they might disappear like (which was released as ), yada yada yada...
AccurateTiming
RepeatedTiming
The internal GeneralUtilities package is often mentioned by people in the know and contains a lot of symbols:
In[]:=
$VersionLength@Names["GeneralUtilities`*"]
Out[]=
13.2.0 for Mac OS X x86 (64-bit) (November 18, 2022)
Out[]=
549
Some of them are really, really useful: e.g. how can you live without once you learnt about it existence?! But in general, it’s hard to know what else is there. But I just have a brilliant realization: if Wolfram developers went into trouble of defining a documentation string for such a function, it should be a real gem! Here are all of these functions. Which one is your favorite?
SetUsage
In[]:=
documentationStrings=Quiet@With[{names=DeleteCases[Names["GeneralUtilities`*"],"Buzz"]},Cases[MessageName[#,"usage"]&/@Symbol/@names[[;;First@FirstPosition[names,_?(StringContainsQ["$"]),Heads->False]-1]],_?StringQ]];Length@documentationStringsStringRiffle[documentationStrings,"\n\n"]
Out[]=
180
Out[]=
AllSameAs[list, val] returns True if all elements of list are SameQ as val.AppendAt[expr, elem, level] appends elem to the end of the last expression at depth level in expr.AppendAt[expr, elem, {, , …}] appends elem to the part of the expr at the given position.AppendToAt[sym, expr, part] sets sym to the result of AppendAt[sym, expr, part].AssociatePairs[{{, }, {, }, …}] gives the association <| , , …|>.AssociationPairs[ , , …] gives the list {{, }, {, }, …}.AssociationTranspose[{, , …}] gives an association of lists, such that part key, n in the result is equal to part n, key in the original list.AssociationTranspose[ , , …] gives a list of associations, such that part n, key in the result is equal to part key, n in the original association.AssociationTranspose[ , , …] gives an association of associations, such that part , in the result is equal to part , in the original association.AttachDebugInfo["context"] finds SetDelayed definitions in the files defining context, and annotates them for use with CallGraphPlot, CallGrid, and CallRules.AttachDebugInfo[symbol] annotates an existing symbol.AttachDebugInfo[{, , …}] annotates several things simultaneously.In addition, any messages or Panics that occur during their evaluation will produce a stack trace.If AttachDebugInfo cannot find any files that define context, it will still annotate definitions for symbols in context, but will not include location information in those annotations.BagContents[bag] returns the entire contents of a bag.Benchmark[f, g, {, , …}] gives {{, }, {, }, …}, where is the time taken to evaluate f on the input g[], as measured by AccurateTiming.Benchmark[f, g] chooses the adaptively by observing the execution of f.BenchmarkPlot[f, g] plots the time taken to execute f with input g[n] against integer n, where the n are chosen automatically.BenchmarkPlot[f, g, {, , …}] uses the explicit to generate input g[] for f.BenchmarkPlot[{, , …}, …] plots the time taken for each of the .BenchmarkPlot[data, …] plots the results of a previous Benchmark computation.BytePlot[{RowBox[{StyleBox[bytes, TI], StyleBox[…, TR]}]}] produces a graphical representation of the list of bytes.BytePlot["bytes"] produces a graphical representation of the byte string bytes.BytePlot[bytearray] produces a graphical representation of the content of the ByteArray bytearray.BytePlot[file] produces a graphical representation of the binary content read from the file file.CacheTo[symbol, key, expr] returns symbol[key] if it exists, otherwise evaluates expr, stores it under symbol[key], and returns it.CallGraph[expr] gives {graph, result}, where graph is a Graph object of consisting of edges Hold[] Hold to indicate that function called .Functions must be annotated with AttachDebugInfo or GetDebug prior to calling CallGraphPlot.CallGraphPlot[expr] gives {graph, result}, where graph visualizes function calls that occur during evaluation of expr.Functions must be annotated with AttachDebugInfo or GetDebug prior to calling CallGraphPlot.CallGrid[expr] gives {grid, result}, where grid shows the nesting of function calls that occur during evaluation of expr.Functions must be annotated with AttachDebugInfo or GetDebug prior to calling CallGrid.CallRules[expr] returns {rules, result} where rules is a list of rules showing the result of function calls that occured during evaluation of expr.Functions must be annotated with AttachDebugInfo or GetDebug prior to calling CallRules.CallTimings[expr] returns {rules, result} where rules is a list of rules showing the time taken for function calls that occured during evaluation of expr.Functions must be annotated with AttachDebugInfo or GetDebug prior to calling CallTimings.CatchAll[expr] returns $Aborted if any uncaught Throw or Abort occurs during the evaluation of expr.CatchAll[expr, result] evaluates result in the cause of an abort.CatchFailure[body] is a macro that evaluates body, but returns a Failure[…] object if a ThrowFailure[…] occurred during evaluation. The current function is automatically used as the message head.CatchFailure[head, body] explicitly uses head as the message head for the failure message.CatchFailureAndMessage[body] is a macro that evaluates body, but returns a Failure[…] object and issues a message if a ThrowFailure[…] occurred during evaluation. The current function is automatically used as the message head.CatchFailureAndMessage[head, body] explicitly uses head as the message head for the failure message.CatchFailureAsMessage[body] is a macro that evaluates body, but issues a message if a ThrowFailure[…] occurred during evaluation. The current function is automatically used as the message head.CatchFailureAsMessage[head, body] explicitly uses head as the message head for the failure message.Checked[f][RowBox[{StyleBox[args, TI], StyleBox[…, TR]}]] is the operator form of EvaluateChecked, which evaluates f[args…], returning early with a Failure[…] object if a message occured during evaluation.Checked[f, g][RowBox[{StyleBox[args, TI], StyleBox[…, TR]}]] evaluates f[args…], returning g[Failure[…]] if a message occured.CollectTo[syms, body] creates a bag for each of the symbols in the list syms, and populates them as described by body. The bags are then converted to lists. • The code in body must make use of methods for dealing with an Internal`Bag such as Internal`StuffBag.Discounted total of common subsequence lengths.ComposeUntil[test, f, {,,…}] computes f[] until test gives True, or returns $Failed if none do.ComputeWithProgress[worker] runs a progress-monitored computation implemented by worker.ComputeWithProgress[worker, summary] summarizes the computation with summary text.The function worker will be called with one argument: a callback function pf. • worker should call pf when possible, passing it progress information.• pf should be called in one of two ways by worker: • pf[frac], where frac is single real number between 0 and 1 • pf[<|progress frac, …|>], where additional keys can include more info• The summary can be a single string, that describes the computation generically.• The summary can also be an association with the following keys:
• If not provided, Dynamic inherits from Static which inherits from Generic.• Summaries can be strings, None, or general functions.• The Generic summary should not include any template parameters.• The other summaries can include template parameters using the normal `name` StringTemplate syntax. • The available template parameters are: • progress, the fraction complee • any other key-values given to pf • any key-values provided to the StaticData optionThe following options are supported:
• The PreemptiveFunction, if provided, will cause a scheduled task to be started that will call the function periodically. The function should generate the current progress values that would normally be fed to pf. Use this feature if your worker function blocks for long periods of time in a C++ or kernel function, etc.Cond[test, f][e] yields f[e] if test is True, otherwise yields e.ConditionalBody is a macro that is used to efficiently implement the common idiom of a system symbol that performs a set of checks, and if any of them fails, issues a message and returns unevaluated. • It is used in the following way:foo[] := ConditionalBody , , , , ... body• The are ordinary expressions that should evaluate to True.• If they do not, the corresponding is used to generate a message: • msgname generates a message foo::msgname • {msgname, args…} generates a message with the given arguments • HoldForm[$LHS] allows the entire left-hand-side to be used as a message argument• If body yields $AbortBody (or Fail), then it will again fail to evaluate.ContainsQ[expr, pattern] returns True if expr contains pattern at any level. ContainsQ[pattern] is the operator form of ContainsQ.• ContainsQ is the negation of FreeQ.CreateTimer[f, interval] creates an pure function timer such that timer[time] will call f[] if time equals or exceeds the previous time by at least interval. CreateTimer[{,,…},…] calls all of the in sequence.• time and interval can be atomic numbers, or can be tuples of numbers.• Tuples requires that all time components equal or exceed the previous time components.DeclareArgumentCount[symbol, n] specifies that symbol is a function that takes exactly n arguments.DeclareArgumentCount[symbol, {min, max}] specifies that symbol takes between min and max arguments.• DeclareArgumentCount basically just sets up a downvalue to do error reporting.• When symbol is called with the wrong number of arguments, it will issue the appropriate system message and return unevaluated.DeepCases[expr, patt] is like Cases but looks for patt arbitrarily deep in expr.• See also UniqueCases, DeepUniqueCases.DeepUniqueCases[expr, patt] is like Cases but looks for patt arbitrarily deep in expr, and returns deduplicated results.• See also UniqueCases, DeepCases.DefineAlias[newsymbol, oldsymbol] does what it says on the tin.DefineLiteralMacro[symbol, lhs := rhs, …] defines a literal macro such that when lhs it is substituted for rhs without evaluation.The same replacement is attached to symbol for use outside a macro context.DefinitionCases["context", patt] finds all definitions of symbols in context that contain patt at any level.• See also DefinitionContextCases, PrintDefinitionCases, SymbolCases.DefinitionContextCases["", ""] finds all definitions of symbols in that depend on a symbol from .• See also DefinitionCases, PrintDefinitionCases, SymbolCases.DelegateIterator[iter] when returned by an iterator indicates that iter should be consumed in-place before calling the iterator again.Discard[list, crit] discards elements of list for which crit[elem] gives True.Discard[crit] is the operator form of Discard.DiscardStrings[strings, patt] gives a list of those strings which do not match the string pattern patt.DiscardStrings[strings, {, , …}] discards strings that match any of the .DiscardStrings[patt] is the operator form of DiscardStrings.DoWhile[body, test] will evaluate body once, and then continue to evaluate it as long as test returns true.EchoGroup["label"][body] echos label, and makes any echos that occur within body indented.• See also EchoRaw, EchoHold, EchoSequence, Tap, EchoSet, EchoSymbol, EchoTag, DisableEcho.EchoHold[expr] evaluates and returns expr, while simultaneously printing the expr result.• See also EchoRaw, EchoGroup, EchoSequence, Tap, EchoSet, EchoSymbol, EchoTag, DisableEcho.EchoPerformance[expr] evaluates expr while printing the evaluation timing (seconds), max memory used (bytes), and using the head as label.EchoPerformance[expr, label] display label instead of expression head.EchoPerformanceRepeated is like EchoPerformance but with timing computed on multiple evaluations.EchoRaw[expr] prints the undecorated InputForm of expr and returns it unevaluated.• See also EchoHold, EchoGroup, EchoSequence, Tap, EchoSet, EchoSymbol, EchoTag, DisableEcho.EchoSet[sym, value] sets sym to value, while simultaneously printing sym = value.• See also EchoRaw, EchoHold, EchoGroup, EchoSequence, Tap, EchoSymbol, EchoTag, DisableEcho.ElementQ[elem, list] gives True if the value elem is present in list.ElementQ[list] is the operator form of ElementQ.ElidedForm[expr] renders as a dynamic, compact form of expr.EnlargeBounds[{{l, r}, {b, t}}, frac] enlarges the given bounding box by the fraction frac of its width and height.EnlargeBounds[{{l, r}, {b, t}}, {{dl, dr}, {db, dt}}] enlarges the given bounding box by the given amount on each side.EnsureDirectory[path] ensures that a path exists on disk, creating it if it does not.EvaluateCached[key, expr] checks key in the system cache, returning the associated value if present, and storing and returning the result of evaluating expr if not.EvaluateCached[key, test, expr] only stores the result of evaluating expr if test[result] gives True.EvaluateChecked[body] evaluates body, returning early with a Failure[…] object if a message occurs during evaluation.EvaluateChecked[body, f] returns f[Failure[…]] if a message occurs.Excise[RowBox[{StyleBox[args, TI], StyleBox[…, TR]}]] evaluates to an empty sequence, effectively removing its arguments without evaluation.ExportStructuredHDF5["file", expr] exports expr to an HDF5 file, which can be a list of associations or an association of associations.Invidiual values can be RawArrays, ByteArrays, or (lists of) strings, reals, or integers.The option Append controls whether an existing dataset will have new values appended to it.FailureQ[expr] gives True if expr has head Failure or is equal to $Failed or $Aborted.FileCasesIterator["file", patt] gives an iterator that yields string matches of a string pattern patt in the contents of the given file.FileCasesIterator[stream, patt] yields matches from a stream.FileLines[path] gives a list of lines contained in the given file.FileLines[path, n] gives the first n lines.FileLinesIterator["file"] gives an iterator that yields lines from the given file.FileLinesIterator[stream] yields lines from the given stream.FileQ[path] returns True if path exists and is an ordinary file.FileString[path] gives a string of the contents of a file.FilterOptions[symbol, RowBox[{StyleBox[rules, TI], StyleBox[…, TR]}]] evaluates to a sequence of only those rules that are valid options for symbol.FilterOptions[RowBox[{StyleBox[rules, TI], StyleBox[…, TR]}]] evaluates to a sequence of only those rules that are valid for the head surrounding FilterOptions.FirstMatchIndex[list, patt] gives the first i for which matches the pattern patt.FirstMatchIndex[list, patt, default] gives default if no element matched.FirstMatchIndex[patt] is the operator form of FirstMatchIndex.FoldEmit[f, , {, , …, }] recursively calculates f[, ] to produce {, {, , …, }}, where each f[, ] should give the {, } to use in the next iteration.FoldEmitRecurse[f, , {, , …, }] works like FoldEmit[…], except each f[, ] produces {, , }, and the are nested onto the .FoldRecurse[f, , {, , …, }] recursively calculates f[, ] to produce Composition[, , …, ] applied to , where each f[, ] should give {, }.GetFragment is used to re-loads only a fragment of a package, which can be faster than re-loading all the package.GetFragment[fragment] loads fragment. fragment can be a file name or a directory name.GraphicsBounds[graphics] gives a list {{left, right}, {bottom, top}} of the coordinates that bound all graphics primitives occuring in graphics.HasDefinitionsQ[sym] returns True if sym has any top-level values (Down, Own, etc) or any Messages.HasDefinitionsQ["sym"] does the same.HoldFunction[…] acts like Function[…] except the resulting pure function has attribute HoldAllComplete.ImportStructuredHDF5["file"] reads an HDF5 file previously created by ExportStructuredHDF5.The option ArrayForm controls how arrays of numbers are returned:
IndexOf[list, expr] gives the first i for which === expr.IndexOf[list, expr, default] gives default if no element was equal to expr.IndexOf[expr] is the operator form of IndexOf.IndicesOf[list, expr] gives a list of the for which === expr.IndicesOf[expr] is the operator form of IndicesOf.InertExpressionQ[expr] attempts to detect if expr contains evaluatable code.InformationPanel[title, data] create a 2-columns information table with title title.• data should be a list of rules (including delayed rules) { , , etc.}.• The following special keys can be used to display key-less values:
• Missing values are not displayed.• The following options can be given:
• example:InformationPanel Evaluation Progress, Center :> ProgressIndicator[Clock[10]/10], Time elapsed :> TimeString[Clock[10]], Objective value :> SetPrecision[RandomReal[], 3], Method :> Newton, Center :> RandomImage[1, {10, 10}, ImageSize Tiny], Right :> NiceButton[Stop, Print[Stop!]] , UpdateInterval .5• guidelines: - Use NiceButton to create buttons Stop, Pause, etc. - Use TimeString to show elapsed time. - Use SetPrecision to shorten real numbers (typically use p=3). - To display evaluation progress information: - Use PrintTemporary/NotebookDelete to display the panel. - Plots and other time-consuming operations should be done outside the dynamic panel.• The head of the output depends on the environnement: /; $Notebooks (FE): - UpdateInterval None: Deployed[Grid[…]] - UpdateInterval Except[None]: DynamicModule[…] /; !$Notebooks (Terminal): - UpdateInterval None: String (currently formats: String, NumericQ, Infinity, None, Quantity, Around, and extracts the first element in: Style and Tooltip; anything else is not displayed.) - UpdateInterval Except[None]: $Failed (caller should provide appropriate error handling).InheritedMessage["msg", RowBox[{StyleBox[args, TI], StyleBox[…, TR]}]] issues the message named msg with the head based on the nearest CatchFailure.InternalFailure[…] represents a failure caused by a Panic, and always contains the fields Tag, Message, and MessageArguments (which can be None).• An optional field called Information can contain an association, any fields within it will be presented using PrettyGrid.IntegerQ[expr] gives True if expr is an integer, and False otherwise. Value given by an iterator that has been exhausted.JoinIterator[, , …] builds an iterator that yields the elements from until exhausted, then , etc.JoinMap[f, list] returns Join[f[], f[], …], where are elements of list.JoinMapIterator[gen, input] builds a new iterator that yields from the iterator built by gen[] until exhausted, then from gen[], ….JoinTo[lhs, list] joins the list to lhs, updating the value of lhs.JoinTo[lhs, list1, , …] joins several lists to lhs.KeyAddTo[assoc, key, n] adds n to the value associated with key key of an association.KeyAppendTo[assoc, key, elem] appends elem to the value associated with key key of an association.KeyIncrement[assoc, key] adds 1 to the value associated with key key of an association.KeyJoinTo[assoc, key, list] joins list to the value associated with key key of an association.KeyPrependTo[assoc, key, elem] prepends elem to the value associated with key key of an association.KeyUnionTo[assoc, key, list] unions list with the value associated with key key of an association.Labelling[{,,…}] gives {ids, labels} where ids is a list of positive integers , and labels is a list such that is .Labelling[list, n] labels the parts at level n of list.LayerPlot[edges] produces a layered graphical plot, where edges is a list of pairs of vertex ids, which must be integers between 1 and n.LookupOr[assoc, keys, func] looks up a set of keys, calling func[key] if a key is missing from assoc.MacroEvaluate[expr] evaluates all macros present in expr and then evaluates the result.MacroExpand[expr] evaluates all macros present in expr and returns the result in a Quoted expression.Anywhere in a macro, ' can be used to inject EchoRaw calls, '' to inject EchoHold calls, and ''' to wrap a function in Tap.MacroExpandList[expr] expands all macros that occur in expr, returning a list of Quoted expressions that give the intermediate results after each expansion step.MacroPanic[] should be called to complain about the current macro's invocation being invalid.MacroPanic["msg", RowBox[{StyleBox[args, TI], StyleBox[…, TR]}]] gives a more specific message.MacroPanic[head::msg, RowBox[{StyleBox[args, TI], StyleBox[…, TR]}]] gives a more specific message.MacroRules[symbol] gives all the macro application rules associated with the head symbol.MapIf[f, test, list] applies f to only those values in list for which test[] gives True.MapIf[f, test] is the operator form of MapIf.MapSequence[f, , , …] returns Sequence[f[], f[], …].Match[value, , , …, default] matches the value to the in turn and gives the corresponding , or evaluates default if none matched.Match[value, RowBox[{StyleBox[patts, TI], StyleBox[…, TR]}], …] panics if none of the patts matched.Match[patts] is the operator form of Match.MatchIndices[list, patt] gives a list of the i at which pattern patt matches.MatchIndices[patt] is the operator form of MatchIndices.MatchValues is a macro that collects several separate downvalues of a function together.MatchValues can only be used to define a function of one argument.• The usage of MatchValues is as follows:func = MatchValues lhspatt := rhsbody; lhspatt := rhsbody; ... (default)• If provided, the final expression will be used as the default value if no other patterns matched.• The special value % refers to the func itself when used in a body. This makes for easy recursion.Memoized[body] specifies that body should be evaluted but cached so that subsequent calls with the same value for any bound symbol use the cached value.Memoized[body, Method method] can be used, where method is one of {Association, Symbol, Inline, SystemCache}, to choose a specific caching method.MLExport[file, expr] exports expr to file in a format suitable when expr contains numerical arrays.FloatType xxx allows to set the encoding of real numbers (Real64 or Real32)ComplexType xxx allows to set the encoding of complex numbers (Complex128 or Complex64)MantissaPrecision p keeps only p bits of the mantissa (does not change the encoding format) of real values in base 2. This will not change the file size but will make it more compressible.p = 53 corresponds to double precision (64 bits)p = 24 corresponds to single precisionp = 11 corresponds to half precisionMLImport[file] imports file created by MLExport.ModuleScope[body] works like Scope[body], but uses Module to localize variables instead of Block.• See also Scope, ScopeVariable.MonitorStack[expr] creates a popover that dynamically shows the current value of the stack while expr evaluates.Functions must be annotated with AttachDebugInfo or GetDebug prior to calling MonitorStack.Use the option Delay secs to introduce an artificial delay prior to each new call being evaluated.OnExit[cleanup] within a Scope[…] will ensure that cleanup is run when the Scope is exited.• The OnExit[…] must be reached before body will be run.• The cleanup code will be run even if the Scope is exited via a Throw, Return, etc.OnFailure[f, expr] gives f[expr] if FailureQ[expr] is True, otherwise gives expr.OnFailure[f] is an operator form of OnFailure.OpenStreamQ[stream] returns True if stream is opened, and False otherwise.PacletCacheDir["pacletname"] returns a unique directory for a paclet in which MX caches can be saved.• pacletname must be the name of a valid paclet.• The resulting directory is unique in the following ways: • Different kernel verions will produce different directories. • Different versions of a paclet will produce different directories. • Different locations of a paclet on disk will produce different directories.• See also PacletLoadCached, $PacletLoadCaching, ClearPacletLoadCache.PacletLoadCached["pacletname", initFunction, saveFunction, restoreFunction] is meant to be called from a paclet's Kernel/init.m file.• It provides a standardized mechanism to have MX files saved after the first successful load of a load.• On first load, initFunction[] will be called to load the paclet normally.• If this completes without a message and does not return $Failed, saveFunction[…/Definitions.mx] will be called. • Typically this function should just call DumpSave.• Subsequent calls to PacletLoadCached will call restoreFunction[…/Definitions.mx] to load the saved MX file. • Typically this function should just call Get.• The …/Definitions.mx file is stored in PacletCacheDir[pacletname].• $PacletLoadCaching determines if this mechanism will actually be engaged. • If cached loading is skipped because it is disabled, the string Disabled will be returned. • Other failures will return PathFailure, InitFailure, SaveFailure.• If GeneralUtilities`PackageScope`$PacletLoadCachedLogging is True, the actions taken will be printed.• See also PacletCacheDir, $PacletLoadCaching, ClearPacletLoadCache.PairQ[expr] returns True if expr is a list of length two, and False otherwise.Panic[] aborts the computation when an unexpected internal condition occurs.Panic["tag"] gives a single-word label or tag for the kind of unexpected condition, which should be CamelCase.Panic["tag", "msg", RowBox[{StyleBox[args, TI], StyleBox[…, TR]}]] provides more information, formatting as in Message.When $DebugMode is True, any information will be returned from the containing CatchFailure as an InternalFailure object.In production, $Failed will be returned from the containing CatchFailure and a message about an unspecified internal error will be printed.If there is no containing CatchFailure, the entire computation is aborted with Abort[].The last InternalFailure to be thrown is stored in Internal`$LastInternalFailure.The last uncaught failure is stored in Internal`$LastUncaughtFailure.ParseMethod[userspec, "" , …] parses a Method specification userspec against the given table of allowed methods, throwing failures as appropriate.ParseMethod[userspec, methodtable, paramhandler] specifies how method parameters are handled/verified.• The should be pairs of the form {func, <| {, }, …|>}. • The are the allowed parameters to . • The are arbitrary expressions that will be given to parser. • The are the defaults to use for the parameters. • func is a function that will be applied to the final parsed association.• The first method is the default method.• The special key $CommonParameters can contain parameters that are shared by all methods.• If a method name starts with a $, it will not be shown in error messages.• paramhandler can be one of the following:
• If provided, paramparser is called like paramparser[key, userspec, , ]. • If it returns $Failed, an appropriate generic message will be issued. • If it returns $Failed[reason], a more specific message will be issued.• The paramparser is not applied to defaults.PartitionBy[list, f] splits list into sublists, splitting after each for which f[] is True.PatternHead[patt] gives the symbol to which a definition's left hand side will be bound, if any.PatternSort[{, , …}] returns the in order of most specific to least specific.PosetSort[list, test] sorts list such that if test[, ] gives True, element precedes element .PrefixQ[, ] gives True if is a prefix of $list1.PrefixQ[] is the operator form of PrefixQ.PrintCalls[expr] prints each call as it happens during the evaluation of expr.Functions must be annotated with AttachDebugInfo or GetDebug prior to calling PrintCalls.PrintDefinitionCases["", patt] finds all definitions of symbols in context that contain patt at any level, and prints them, highlighting the occurences of patt.• See also DefinitionCases, DefinitionContextCases, SymbolCases.PrintDefinitions[symbol] creates a window containing a browseable hyperlinked listing of definitions associated with symbol. PrintDefinitions["pattern"] tries to find a unique symbol matching the string pattern.• You can click on an underlined symbol to pop up a new window for its definitions.• Mousing over a symbol with a definition will show a summary of the definition in a tooltip.• The pattern usage can be useful for print definitions of symbols in private contexts.• Printed definitions can be modified and then run to patch the existing definition.• Color communicates symbol context:
• See also PrintDefinitionsLocal.PrintDefinitionsLocal[symbol] prints a browseable hyperlinked listing of definitions associated with symbol.• See also PrintDefinitions.PythonBytes[bytearray] gives a string representing the bytes in bytearray formated as a Python bytes.PythonBytes[{RowBox[{StyleBox[integers, TI], StyleBox[…, TR]}]}] gives a Python bytes from a list of integers interpreted as bytes values.Quoted[code] is the inert body of code for the purposes of macro expansion.RaggedDimensions[data] returns the dimensions of data, except it considers ragged levels to have size All, unlike Dimensions, which immediately terminates when it encounters a ragged level.ReapBag[body] evaluates body, returning a list of all expressions inserted via SowBag[expr].Construct[f,x] gives f[x].Construct[f,,…,] gives f[,…,].ScanIndexed[f, expr] evaluates f on each element of expr, giving the part specification as the second argument to f.ScanIndexed[f] is the operator form of ScanIndexed.ScanThread[f, {,,…}] repeatedly evaluates f applied to successive elements taken from each .ScanThread[f] is the operator form of ScanThread.Scope[body] is a macro that expands to a Block with automatically populated local variable list.• Variables are detected syntactically by the presence of = and := within body.• ^= and ^:= can be used to avoid this localization.• {,,…} = rhs will localize , , ….• sym := rhs will localize sym.• Local functions definitions head[…] := rhs do not cause localizalization of head.• ScopeVariable[,,…] can be used to ensure variables are localized without relying on assignment.• See also ScopeVariable, ModuleScope.ScopeVariable[,,…] can be used in a Scope or ModuleScope to cause particular variables to be localized.• See also Scope, ModuleScope.Search[expr, ispec] return the first iteration to yield TrueSearchMaximum[expr, ispec] returns the i that yields the maximum value for expr, and expr itselfSelectFirstIndex[list, crit] gives the first i for which crit[] yields True.SelectFirstIndex[list, crit, default] gives default if no element matched.SelectFirstIndex[crit] is the operator form of SelectFirstIndex.SelectIndices[list, crit] gives a list of the i for which crit[] yields True.SelectIndices[crit] is the operator form of SelectIndices.SelectIterator[input, criterion] builds an iterator that yields the elements of the input input for which criterion[] is True.SelectStrings[strings, patt] gives a list of those strings which match the string pattern patt.SelectStrings[strings, {, , …}] matches any of the .SelectStrings[patt] is the operator form of SelectStrings.Seq[arg_] evaluates to arg and Seq[args___] evaluates to Sequence[args], bypassing SequenceHold.SetRelatedSymbolGroup[, , …] ensures that the will mention each other in their usage messages.• The must use SetUsage to benefit from this feature.• The call to SetUsage must come *after* the call to SetRelatedSymbolGroup.SetupTeardown[setup, body, teardown] evaluates setup, then body, and then teardown, even if an Abort or Throw occurs during evaluation.SetUsage["symbol[...]_does_something"] sets the usage message for symbol, which should be a symbol on the current $ContextPath (usually this is the case). SetUsage[symbol, "usage"] explicits specifies the symbol to attach the usage to.• Use a single line for each separate usage, using backslash to continue lines if they would otherwise overflow a line in your editor. • Tables (of any size) can be specified using |:| a | b | c || d | e | f |which formats as:
• Table rows must start and end with a |, and interior | must be seperated by spaces on both sides.• If the second row of a table consists of only --- entries, the first row will be styled in bold.• Bullets can be written by starting a line with *.• Characters that are otherwise interpreted can be escaped by writing their base 10 character code via :dddd.• The following special syntax is supported:
Slice[,,…][expr] gives Part[expr,,,…].Slice[…] represents an operator form of Part.SoftPanic[…] sets Internal`$LastInternalFailure as in Panic[…], but does not throw anything or abort.SowBag[expr] adds expr to the list of expressions that will be returned by the innermost containing ReapBag.StaticCallGraphPlot[context] plots the dependency graph between symbols in context.• Symbols in any parent context of context are included, but only in the form of symbols that use or are used by symbols in context.• The option VertexLabels can be set to:
• See also StaticCallGraph.StreamExecute["file"] gives the contents of a file as a string.StreamExecute["!cmd"] executes a shell command, and gives its output as a string.StreamExecute[spec, "term"] reads until the terminator term is found.StreamExecute[spec, {"", "", …}] reads until one of the is found.StreamExecute[spec, term, All] returns multiple strings, seperated by term.StreamExecute[spec, term, n] returns the first n results.StreamIterator["file", patt] gives an iterator that reads elements of the given type from the file.StreamIterator[stream, patt] reads from a stream.StringPatternQ[expr] gives True if expr is a valid string pattern, suitable for use with e.g. StringMatchQSwap[lhs, rhs] swaps lhs with rhs by using a temporary value.SymbolCases["context", patt] finds all symbols in context which have a definition that contains patt at any level.• See also DefinitionCases, DefinitionContextCases, PrintDefinitionCases.Tap[f] gives a TappedFunction[…], which yields the same result as f when applied, but prints the input arguments and final result.• See also EchoRaw, EchoHold, EchoGroup, EchoSequence, EchoSet, EchoSymbol, EchoTag, DisableEcho.TappedFunction[f] yields the same result as f when applied, but prints the input arguments and final result.Tee[f, g][expr] evaluates f[expr] but returns g[expr].TestAssoc[,,…] makes an association <|A,B,…|>.TestSetsEqual[a,b] tests that a and b have the same elements, returning True or False.TestSetsEqual[a,b,aextra] calls aextra on the first element in a not in b.TestSetsEqual[a,b,aextra,bextra] calls bextra on the first element in b not in a.TestSubsetQ[a,b,f] tests that b is a subset of a, and calls f if not.• f is passed the first element in b that is not in a.TestTable[{,,…},{,,…},…] makes a list of associations {<|A,B,…|>,<|A,B,…|>,…}.ThrowFailure["msg", RowBox[{StyleBox[args, TI], StyleBox[…, TR]}]] throws a Failure object to be caught by the nearest CatchFailure, which will attach the associated head.ThrowFailure[head::msg, RowBox[{StyleBox[args, TI], StyleBox[…, TR]}]] specifies the head to use for the Failure object.ThrowFailure[] just throws $Failed.ThrowRawFailure[expr] throws an expression to be caught and returned by the nearest CatchFailure.ToAssociations[expr] replaces all lists of rules occuring in expr with associations having the same keys and values.ToQuoted[head, , , …] transforms to Quoted[head[, , …]].ToRegularExpression[patt] gives a string containing a regular expression that matches the string pattern patt.TraceLoading[body] reports all file and MX load events trigerred during the evaluation of body.• See also TraceUnpacking.TraceUnpacking[body] collects statistic about unpacking and how often it occurs.• See also TraceLoading.TrimLeft[lists] trims lists to the length of shortest element, removing elements from the left.TrimRight[lists] trims lists to the length of shortest element, removing elements from the right.UnionTo[lhs, list] unions the list with lhs, updating lthe value of hs.UnionTo[lhs, list1, , …] unions several lists wtih lhs.UniqueCases[expr, patt] is like Cases, but returns deduplicated results.• See also DeepCases, DeepUniqueCases.UnpackAssociation[assoc, "", "", …] extracts the given keys from the association and sets variables named .UnpackAssociation[assoc, , , …] uppercases the first letter of the symbol name to get the key.UnpackAssociation[assoc, :"", …] gives an explicit name for each symbol.UnpackAssociation[assoc, …, "Default" def] uses the value def if a key is missing from assoc.UnpackAssociation[assoc, …, "DefaultFunction" func] calls func[key] if a key is missing from assoc.UnpackOptions[, , …] extracts options with names , , … and assigns them to the , where the keys are the title cased version of the symbol names.UpdatePacletWithProgress["pacletname"] downloads or updates the given paclet, displaying a nice progress bar via ComputeWithProgress for longer downloads.UpdatePacletWithProgress["pacletname", "summary"] displays the given text (which should be static).• The default summary is the same generic language that is used by PacletManager.UseMacros[body] does nothing more than trigger macro expansion, use it if you want to use macros in a function but dont need Scope.ValidFailureQ[expr] gives True if expr is a valid Failure object, and False otherwise.ValidGraphicsQ[graphics] returns True if graphics is a Graphics expression containing only valid graphics primitives and directives.ValidPropertyQ[symbol, elem, list] returns True if an element of list matches elem, and False otherwise.If False, an appropriate symbol:xxx message will be displayed.Elements should be strings or symbols.ValidPropertyQ[symbol, elem, , ] checks if elem belongs to or but omits the elements of in messages. This is used to specify elements that are allowed but not documented.The following options can be given:
When[test, body][e] evaluates body if test[e] is True, otherwise yields e unchanged.When[, , , , …][e] evaluates the tests in turn until one gives True, otherwise yields e unchanged.WhenNot[test, body][e] evaluates body if test[e] is not True, otherwise yields e unchanged.WhenNot[, , , , …][e] evaluates the tests in turn until one is not True, otherwise yields e unchanged.WithMessageHandler[body, f] evaluates f[failure] whenever a message occurs during the evaluation of body, where failure is a Failure[…] object that represents the message.
p
1
p
2
key
1
val
1
key
2
val
2
key
1
val
1
key
2
val
2
key
1
val
1
key
2
val
2
key
1
val
1
key
2
val
2
assoc
1
assoc
2
key
1
list
1
key
2
list
2
key
1
assoc
1
key
2
assoc
2
key
1
key
2
key
2
key
1
spec
1
spec
2
n
1
n
2
n
1
t
1
n
2
t
2
t
i
n
i
n
i
n
1
n
2
n
i
n
i
f
1
f
2
f
i
f
i
f
j
f
i
f
j
e
1
e
2
e
i
"Generic" | summary of the computation without any run-specific detail |
"Static" | summary with basic detail that won"t change during a run |
"Dynamic" | summary including changing details |
"Details" | additional details, without repeating main summary |
"StaticData" | include additional parameters for summary templates |
"ReportingForm" | one of None, Automatic, "Panel", or "Print" |
"UpdateInterval" | either Automatic or a number (seconds) |
"MinimumProgressTime" | how long to wait before displaying any content at all |
"CleanupFunction" | function to call if computation is aborted or ends normally |
"CompletionFunction" | function to call if computation ends normally |
"PreemptiveFunction" | function to call preemptively (use for blocking workers) |
"TimeEstimate" | initial estimate of how long computation will take |
"DynamicContainer" | Hold[variable] to set to the dynamic content, rather than printing it |
"PrintEllipses" | if True, printing to stdout will print ellipses instead of repeated messages |
test
1
errorSpec
1
test
2
errorSpec
2
test
i
errorSpec
i
f
1
f
2
f
i
context
1
context
2
context
1
context
2
patt
1
patt
2
patt
i
list
i
x
0
u
0
u
1
u
n
x
i
u
i
x
n
v
1
v
2
v
n
x
i
u
i
x
i+1
v
i+1
x
0
u
0
u
1
u
n
x
i
u
i
x
i+1
v
i+1
f
i+1
f
i
v
i
x
0
u
0
u
1
u
n
x
i
u
i
g
1
g
2
g
n
x
n
x
i
u
i
x
i+1
g
i+1
"RawArrays" | return as RawArray objects |
"Lists" | return as ordinary lists |
"Placeholders" | return as H5DatasetPlaceholder[dims] objects |
list
i
i
j
list
i
key
1
val
1
key
2
val
2
Left | displays the value on the left side |
Center | displays the value in the center |
Right | displays the value on the right side |
UpdateInterval | None | refreshing interval, or None for a static panel |
TrackedSymbols | {} | symbols to be tracked dynamically |
ColumnWidths | {Automatic, Automatic} | width of colums |
input
1
input
2
input
1
input
2
e
1
e
2
e
i
e
1
e
2
list
2
e
1
e
2
id
i
labels
id
i
e
i
e
i
e
i
arg
1
arg
2
arg
1
arg
2
patt
1
val
1
patt
2
val
2
patt
i
val
i
method
1
methodspec
1
methodspec
i
param
1
type
1
default
1
param
j
method
i
type
i
opt
i
"Pattern" | treat the type i |
"Predicate" | treat the type i |
"Function" | treat the type as functions to be applied to user specs |
paramparser | a function passed the user sepc, type, and default value |
type
i
default
i
e
i
e
i
patt
1
patt
2
patt
i
e
i
e
j
e
i
e
j
list
1
list
2
list
2
list
2
context
1
System`Private` | red |
*`PackageScope` | salmon |
*`PackagePrivate` | gray |
Developer`, Internal` | cerulean |
GeneralUtilities` | pastel blue |
System`, Global` | black |
any top-level context | gray |
x
1
x
n
x
1
x
n
expr
1
expr
2
expr
i
sym
1
sym
2
sym
1
sym
2
var
1
var
2
var
1
var
2
e
i
e
i
e
i
patt
1
patt
2
patt
i
sym
1
sym
2
sym
i
sym
i
a | b | c |
d | e | f |
foo$ | foo |
foo$i | foo i |
foo$(i,j) | foo i,j |
'foo' | "foo" |
$$ | … |
foo$$ | foo… |
-> | |
part
1
part
2
part
1
part
2
All | show labels on all vertices (default) |
None | do not show any labels |
Automatic | show labels on vertices on non-private symbols |
term
1
term
2
term
i
arg
1
arg
2
arg
1
arg
2
col
11
col
12
col
21
col
22
col
11
col
21
col
21
col
22
arg
1
arg
2
arg
1
arg
2
list
2
Name
1
Name
2
name
i
symbol
1
symbol
2
symbol
1
Name
1
sym
1
sym
2
Sym
1
Sym
2
sym
i
list
1
list
2
list
1
list
2
list
2
"Type" | "property" | the name of element type (property, method, etc.) |
"TypePlural" | Automatic | plurialized name of element type |
MaxItems | 15 | maximum number of elements to be displayed in the message |
SameTest | Automatic | function to determine whether there is a match |
test
1
body
1
test
2
body
2
test
1
body
1
test
2
body
2