# sprint

Definition: | string s = sprint(object x, integer asCh=false 1, maxlen=-1[, nest=0])
Description: | The representation of x as a string of characters is returned, exactly the same as print(fn, x[, asCh[, maxlen]]), except that the output is returned as a string, rather than being sent to a file or device. x: can be any phix object.
asCh: true: | print eg 65 as 65'A',
false: | not top-level,
-1: | sticky/nested false.
1 | if asCh is in {9,10,11} it is treated as {-1,0,1} and becomes the new default.
maxlen: | (desktop only) the maximum desired length in characters of the returned result, anything beyond this is indicated by a trailing "..", potentially in addition to the specified length.
See the technicalia for more details and the nest parameter.
pwa/p2js: | Supported. No maxlen or nest parameters (as yet, see below).
Comments: | The atoms contained within x will be displayed to a maximum of 10 significant digits, just as with print(). An asCh of false means that sprint(65) yields "65" whereas sprint({65,66,67}) yields "{65'A',66'B',67'C'}" and the same for %v in (s)printf() and the ? shorthand. The %V format specifies a -1 for asCh. The presence of the string type makes asCh=true handling less necessary (than Eu) in Phix, except for debugging, where eg {97'a',98'b',"c"} may make it easier for you to realise your mistake than {97,98,"c"} would, or indeed spot such a value as being erroneous in the first place.
Examples: |
    s = sprint(12345)                       -- s is "12345"
    s = sprint({1,2.5,"hello",{4,5.5}})     -- s is `{1,2.5,"hello",{4,5.5}}`
    s = sprint("hello")                     -- s is `"hello"`
    s = sprint("hello"&-1)                  -- s is `{104’h’,101’e’,108’l’,108’l’,111’o’,-1}`
    s = sprint("hello"&-1,-1)               -- s is `{104,101,108,108,111,-1}`
    {} = sprint(0,9) -- (set the default asCh to -1)
Implementation: | See builtins\VM\pprntfN.e (an autoinclude) for details of the actual implementation. (Moved/merged from psprintN.e in 0.8.2)
See Also: | print, sprintf, value, get
Technicalia | For reasons of simplicity, the desired length, if specified, may be exceeded by a few characters, especially when a very small value is passed (eg sprint(12345,maxlen:=1) yields 12345, a length of 5), or when it adds quotes, braces and trailing double dots. It is obviously simpler to leave a small margin rather than try and post-process the results, or of course write a small loop that re-invokes sprint with decreasing length until the result passes muster. At the time of writing there are very ferw known uses of maxlen, one in edix/plade.exw and a couple in pDiagN.e, so there is little reason to support maxlen in p2js.js (obviously let me know should a real need ever arise). There is in fact a fourth parameter, nest, which is intended only for internal use to signify recursive calls, and controls whether or not ".." should be appended when the length exceeds maxlen (if specified). Since print() is in fact implemented as puts(fn,sprint()), there is deliberately no nest parameter for print().