# Library Routines

A large number of library routines are provided. It is strongly recommended to use the index and search facilities (on the far left) to navigate this section effectively, rather than the central content tree (which is more about trying to keep relevant stuff nearby), that is unless of course you already know where you’re going. Suggestions for improvements would always be warmly welcomed.
Some are written in low-level inline assembly, and some are written hll. Most are automatically included as and when needed, but some require an explicit include statement before they can be used. In the latter case, the appropriate include file is noted in the "Definition" part of the description.
Routines are documented using an explicit type declaration style syntax. For example where you see a definition such as

    integer i = length(sequence s)

You should understand that denotes actual statements which look more like:

    i = length(s)

The examples, when provided, often give a clearer illustration of the required syntax than the formal definition at the start.
Some routines are not available on all platforms, in particular there are significant limitations on code that can be run in a web browser, such as not being able to read disk files, load a dll/so, execute system commands, allocate memory, or use multitasking or multithreading.
All library programs are clearly marked with their suitability or otherwise for being transpiled by pwa/p2js so they can be run in a web browser, examples where they cannot include open(), c_func(), system_exec(), and allocate().
Occaionally there are differences between Windows and Linux, for instance message_box() and text_rows() are strictly Windows only, while instance() and cursor() do nothing useful on Linux.
A run-time error message will usually result if an illegal argument value is passed to any of these routines.
It is not permitted to override builtins (at least not globally) or (re)define operators in Phix. While there are a few neat little tricks that sort of thing can achieve, the mental drain of always having to worry whether some builtin routine or operator is doing what you expect (due to some shenanigans hidden away in a [project-specific] file you did not even know existed) becomes significantly reduced, besides the superior and far friendlier compile-time and run-time error messages make modifying several files far less terrifying (or excessively1 compiler-intensive) in Phix than it usually is in other programming languages.
Note there is a somewhat hidden distinction between "true builtins" which cannot be overridden and "utility routines" where that is not quite so strict, as previously briefly mentioned in Declarations. If the implementation notes read something like length()’s `:%opLen in builtins\VM\pLen.e` then it is a true builtin, whereas for something like join()’s `builtins\flatten.e` which has no opcode or "VM" in it, it is just normal hll code, and since the compiler has to allow that, it is therefore also going to (have to) allow you to redefine it. Furture releases are fairly likely to gradually become increasingly stricter in that regard, though nothing immediate is planned, checking that builtins are actually/only defined in the builtins directory has some appeal and is one such possibility.
Of course Phix is an open source language that can be rebuilt in under twenty seconds, so even the core fundamentals can be changed and there is no guarantee that has not already happened, however there is a significant difference between that and "any source file" on a completely untainted installation, or for that matter the exact same source code behaving completely differently in different projects.
1 In some programming languages, simply "touching" a file triggers the compiler into complete overdrive, whereas in Phix, which is much faster to begin with anyway, it makes no difference whatsoever, nor is there ever any need to run around "touching" files because compiler dependencies are foobar’d. It will no doubt horrify some readers to learn that Phix never caches the results of any compilation, but the reality is it simply does not need to - by far the biggest stalling point is when your AV kicks in because a new execuable file has been created, even then at most a few seconds, and prior compilations being cached would have absolutely no effect on that at all.