# string

Definition: | string identifier -- or -- bool b = string(object x)
Description: | This serves to define the string type. You can also call it like an ordinary function to determine if an object is a string.
pwa/p2js: | Supported, however JavaScript is a typeless language, with "`string s`" being mapped to "`let /*string*/ s;`" and there are no run-time typechecks, or at least they are very rare (see implementation notes below). An explicit hll/Phix "if string(x)" and similar expressions all work under pwa/p2js exactly as expected.
Comments: | When invoked as a function, returns true (1) if x is a string otherwise false (0). A type check error occurs if a variable declared as a string is assigned with a dword-sequence. Note the string type is really a sequence of bytes #00..#FF, it can actually hold raw binary as well as ascii and UTF-8 strings, however UTF-32 is 32 bits (or more strictly 21) per character and UTF-16 has 16-bit chars/surrogate pairs, and hence both must instead be kept in a sequence.
Supplemental: | The following are also defined in builtins\ptypes.e (not an autoinclude, but used by [x]pGUI, mpfr, cffi, and hence indirectly builtins\structs.e (which is auto-included as soon as any structs or classes are defined), and the filter() builtin (which is also an autoinclude), so any of those will include it): global type nullable_string(object o) - o must be a string or NULL. global type rid_string(object o) - o must be a string or an integer routine_id. global type atom_string(object o) - o must be a string or an unsigned non-fractional machine-word-sized atom, such as the result from allocate_string() or a char* from c_func(), or any other pointer, or an integer index, or NULL, etc.
Example 1: |
    string s = "hello"
Example 2: |
    if string(x) then
        puts(1,x)
    else
        -- x must be an atom or dword-sequence
        ? x
    end if
Implementation: | There are generic versions of the string function implemented as :%opStr in builtins\VM\pType.e and :%opStr0 in builtins\VM\pJcc.e that the compiler only invokes as a last resort, preferring instead to inline that functionality if the argument is known to be assigned or the result variable, if any, is known to be an integer, ie does not require decref/dealloc. The compiler may also completely omit the test and/or any related code, if type inference/propagation determines that the result will always be true or always false. As already mentioned, builtins/ptypes.e is where the supplemental types are defined. The file pwa/p2js.js defines string() with an optional name parameter, which if not "" triggers unassigned or type check errors, but that (parameter) is not intended for or available from hll/Phix code, and only meant for use in manually hand-crafted replacements elsewhere in p2js.js, and in practice it ended up being invoked (that way) rather more sparingly than first predicted.
See Also: | atom, integer, sequence, object, Sequences, Core Language, Strings
Technicalia | The sq_str() routine can be used to apply a string() test to all top-level elements of a sequence, eg `sq_string({1,1.5,"string",{1,1.5,"string",{}}) ==> {false,false,true,false}`. That routine returns a single true/false if passed an atom or string, otherwise a "flat" sequence of true/false of the same length as the input argument. Note there are no known valid uses of the sq_str() routine, as yet.