Format$ function with indexed & reusable arguments

[bplus]

@RhoSigma  OK quote is updated and I see now that number literals (including a number string, say from String Math, is good to 25 digits with PRINT USING via IndexFormat$, thanks for checking over.

[RhoSigma]

Well, I should probably be careful to call my updates "final" :), but here is another (hopefully) final update to my first post.

It's just one line of code added, but this line prevents the need to write double underscores in the format template just to get one literal underscore in the output.

Also pulled out the function description into a HTML document, which has better formatting options than a plain text description.

BTW, didn't mention this before, while PRINT USING does panic with an "Illegal function call" error when the format template is empty or not having any valid format symbols in it, the IndexFormat() function does gracefully handle those cases. If the template is empty, then you get an empty result. If it's not empty but containing no indexed format tokens, then the result is almost equal to the template, ie. any used escape sequences are evaluated, the rest of the template text is taken as is.

@bplus
Once again be so kind to update the entry in the Samples Gallery.
You need to update the example codebox and the new HTML description codebox, feel free to save the HTML description and add it as attachement, if this fits better for the Samples Gallery.
Thanks in advance.

[bplus]

Wow, that HTML looks great! when I downloaded the attachment to check it out.

@RhoSigma  OK?

Update: I changed name to IndexFormat description.HTML

[RhoSigma]

Thank you B+, looks good, but maybe you wanna correct the 3nd Edit update to 3rd :)

The description format is my new defacto standard, I'm currently reworking all my old function descriptions. It's actually markdown and then exported as HTML. The program I use for it is MarkdownPad2 for windows, a neat 'lil program which is really worth the 15 bucks for registration.

http://markdownpad.com/
unless stated on that side, it also works on Windows 10. You may just get "Awesomium" crashes, which you can avoid by installing the most recent Awesomium package. All described in the online help (FAQ). Works perfect on my Win10 since then.

[bplus]

Thank you B+, looks good, but maybe you wanna correct the 3nd Edit update to 3rd :)

Well maybe I do to keep you happy and so you know your contributions are most welcome :)

While in there modifying, I added brief synopsis of changes in 2nd and 3rd versions, if I misrepresent let me know ;-))

For the 4th, I recommend AI to help write the format statement because it is getting up there in level of complexity. Just kidding, maybe ;-))

[RhoSigma]

Thanx B+, thinking about AI, it's probably already in there, can't remember that I really did something intelligent in my life anytime at all, so in fact everything, my whole life so to say, must be artificial and so everything I do and everything I code :)

[RhoSigma]

This function got a complete overhaul, please visit the first post of this topic to get the update.

Well, most important for me was to get rid of the error situations. Making the function to fail just because of some minor mistakes in the format template always caused pain in my ass. It would be like making PRINT "Hello Word" to fail just because of the missing "l". So now the IndexFormat$() function will try its best with every given format template, but just like in the mentioned example it will probably not give the expected output, if the template does not follow the rules, but that should be already the worst thing to happen.

I've added format symbols for decimal and real outputs, where decimal is (just like bin/hex/oct) limited to output the closest (_ROUND) integer, while real is simply a shortcut for LTRIM$(STR$(num)).

Completly new are the preferences specifiers, which allow to customize the standard behavior of some PRINT USING format symbols and the bin/dec/hex/oct outputs. So you can set an alignment for strings in a fixed length field (\\), group bin/dec/hex/oct outputs in blocks with a certain amout of digits, replace the dollar sign for currency formatting and/or flip the usage of comma and dot as group/decimal separator.

BTW - Happy New Year to everybody

@bplus
when updating the Samples Gallery, please ...
- waive to / remove any ordinal numbers regarding the current version, for the Version tag in the header the date should be enough, in the description text just give an overview of the current features, its irrelevant which feature got added in which version
- completely remove the RhoSigma quote
- attach the new archive, rather than the HTML doc only
Thank You

[bplus]

@RhoSigma  Well I removed the old quote but put in a new one for the present version. A hint of the details should be given and honestly, I've lost track all the things you can do with this. I thought that quote a nice little glimpse. :)

PS date in US would much more likely look like Jan. 2, 2021 or January 2, 2021 (no slash with month names)

[RhoSigma]

Thank you for the update @bplus, looks good.