9

(Mathematica version: 8.0.4)

lst = Names["Internal`*"];
Length[lst]
Pick[lst, StringMatchQ[lst, "*Bag*"]]

gives

293    
{"Internal`Bag", "Internal`BagLength", "Internal`BagPart", "Internal`StuffBag"}

The Mathematica guidebook for programming By Michael Trott, page 494 says on the Internal context

"But similar to Experimental` context, no guarantee exists that the behavior and syntax of the functions will still be available in later versions of Mathematica"

Also, here is a mention of Bag functions:

Implementing a Quadtree in Mathematica

But since I've seen number of Mathematica experts here suggest Internal`Bag functions and use them themselves, I am assuming it would be sort of safe to use them in actual code? and if so, I have the following question:

Where can I find a more official description of these functions (the API, etc..) like one finds in documenation center? There is nothing now about them now

??Internal`Bag
Internal`Bag
Attributes[Internal`Bag]={Protected}

If I am to start using them, I find it hard to learn about new functions by just looking at some examples and trial and error to see what they do. I wonder if someone here might have a more complete and self contained document on the use of these, describe the API and such more than what is out there already or a link to such place.

Cœur
  • 37,241
  • 25
  • 195
  • 267
Nasser
  • 12,849
  • 6
  • 52
  • 104
  • 9
    ?? The official description *is* the so-called "Documentation Center" (aka Help). If there is nothing there, then there is no other structured place. It has happened before: FrontEnd Tokens were introduced around Mathematica 3, but only (partially) documented much later. So, just wait a decade or so and WRI will probably document it. Until then you have to rely on kind developers like Dan Lichtblau et. al. to shed light into the darkness. – Rolf Mertig Dec 29 '11 at 00:33
  • 3
    I have been guilty of recommending undocumented functions without also presenting the caveat of their use. It is hard to not get excited about the latest "trick" I learn and start using it right away, but it may be unwise, and I should not encourage others to follow this practice. Sadly, a number of interesting features and functions fall into this category. I hope there will be official word on functions like `*Bag*` soon. – Mr.Wizard Dec 29 '11 at 03:44
  • 11
    I doubt there will be anything official about those. But they've been around for at least a dozen years, and they're not going away. – Daniel Lichtblau Dec 29 '11 at 03:48
  • 2
    I doubt you'll find any official documentation on ``Internal` `` functions, but searching MathGroup always gives some interesting posts. Also, be careful with these ... for example, [``Internal`Deflatten``](http://stackoverflow.com/a/8502866/695132) is easy to figure out, but it will also happily crash your kernel if you give bad arguments to it. – Szabolcs Dec 29 '11 at 13:50
  • 1
    I think you'll be interested in this question: [What are some useful, undocumented Mathematica functions?](http://stackoverflow.com/q/8461814/695132) We can write up / collect documentation for some useful undocumented features there. Lots of undocumented features are mentioned in different places on MathGroup and here, but it will be good to have an organized collection. Please also see my comment on the main question there. – Szabolcs Dec 29 '11 at 14:01
  • @Lichtblau: Can you elaborate on why you don't think there will be any official documentation on Bag functionality despite the fact that Wolfram engineers have trusted it enough to use it internally over the past decade or so? You feel confident that it won't be removed any time soon. My concern is whether or not there are any caveats about how well it integrates with other Mma functionality ... and if not then what's behind the decision to hold it back from end-users. – StackExchanger Apr 28 '13 at 08:55

1 Answers1

1

The Internal context is exactly what its name says: Meant for internal use by Wolfram developers.

This means, among other things, the following things hold about anything you might find in there:

  • You most likely won't be able to find any official documentation on it, as it's not meant to be used by the public.
  • It's not necessarily as robust about invalid arguments. (Crashing the kernel can easily happen on some of them.)
  • The API may change without notice.
  • The function may disappear completely without notice.

Now, in practice some of them may be reasonably stable, but I would strongly advise you to steer away from them. Using undocumented APIs can easily leave you in for a lot of pain and a nasty surprise in the future.

Sebastian Paaske Tørholm
  • 49,493
  • 11
  • 100
  • 118