Water 5-Common Data Types-String, Bytes, and Char

Contract
Return type	wob
Parameter key	Default value	Type
separator	""	wob
add_starting_separator	false	boolean
add_ending_separator	false	boolean
formatter	"to_htm"	string
Parameter kind	Default value	Type
Other unkeyed arguments	opt

Water Contract
<method join separator =""=wob add_starting_separator=false=boolean add_ending_separator=false=boolean formatter ="to_htm" _other_unkeyed=opt=wob=ekind.code="_body"/>

join concatenates string representations of its arguments and returns the new string.

<join 123 "abc" hi/>

"123abchi"

a wob
Parameter key Default value Type
formatter "to_htm" string
A method or the string name of a method to call with each element as the subject. The result of this call will go into the result string. The default formatter is "to_htm",

<join 123 "abc" true null formatter="to_htm_small"/>

"123abctrue"

The value of formatter need not be a normal formatting method like to_html and to_cxs Any method that takes any object as its subject (or at least all of the kinds of objects that are passed to join and returns a string will do.

<join " good  " "   bye  " formatter="trim"/>

"goodbye"

Note that we must use formatter="trim" instead of formatter=trim because trim is only defined on string, so executing just the symbol will error. Alternatively, if you know that all arguments are strings, you could use formatter=string.trim.

<join " good  " "   bye  " formatter=string.trim/>

"goodbye"

<join "jack" "frost" formatter=string.capitalize/>

"JackFrost"

You can also create your own formatter for custom applications. The formatter should return a primitive.

<join "jack" "frost" formatter=<method null> .0.<to_uppercase/></>/>

"JF"

If the value of formatter is null then no Water formatter method will be called on the items to be joined. If the items are strings ,they will be used as is. Other values will be convereted to strings with a low level function that generally gives a reasonable represenation for most primitives (booleans, chars, numbers, strings, null) and some indicative string for non-primitives that is primarily good for debugging. Use formatter=null when you want your join to be fast and you know you're just joining primitives.

<join "xyz" 321 true <char "a"/>/>

"xyz321truea"

a wob
Parameter key Default value Type
separator "" wob
A string to place between each substring of the result. The default is "" i.e. no separator. Typical separators would be " " to put in a space, or "," to put a comma between values.

<join 123 "abc" <b>hi</b> separator=","/>

"123,abc,<b>hi</b>"

If the separator is not a string, it has the formatter called on it before it is used in the output string. Here we put paragraph breaks between each of the elements to be joined. Since  is not a string and since the default formatter is to_htm the actual separator used is the result of .<to_htm/> which is ""

<join 123 "abc" <b>hi</b> separator=<p/>/>

"123<p></p>abc<p></p><b>hi</b>"

a wob
Parameter key Default value Type
add_starting_separator false boolean
A boolean to say whether to put a separator at the start of the result. The default is false meaning that there will be no separator at the start of the result string.

<join 123 "abc" <b>hi</b> separator="---" add_starting_separator=true/>

"---123---abc---<b>hi</b>"

a wob
Parameter key Default value Type
add_ending_separator false boolean
A boolean to say whether to put a separator at the end of the result. The default is false meaning that no separator wll be added to the end.

<join 123 "abc" <b>hi</b> separator="---" add_ending_separator=true/>

"123---abc---<b>hi</b>---"

<join 123 "abc" <b>hi</b> separator="---" 
             add_starting_separator=true add_ending_separator=true/>

"---123---abc---<b>hi</b>---"

<join "jack" "frost"
        separator="."
        add_ending_separator=true 
        formatter=<method null> .0.<to_uppercase/></>
    />

"J.F."

a wob
Parameter key Default value Type
_subject opt
_subject is optional. If there is a subject that is a primitive value (a boolean, a char, a string, or a number) it will be treated as the first item to join.

3.<join 4 5/>

"345"

If the subject is not a primitive (a vector or a record), each of the vector key fields of the object will be treated just as if they were individual arguments passed to join.

<vector 2 3 4/>.<join separator=","/>

"2,3,4"

You can pass a subject as well as regular args.

<vector 2 3 4/>.<join separator="," 5 6/>

"2,3,4,5,6"

Non vector_key fields are ignored.

<thing 0="zero" 1="one" wieght=27/>.<join/>

"zeroone"

a wob
Parameter key Default value Type
_other_unkeyed opt
The _other_unkeyed parameter behaves just like any Water _other_unkeyed parameter. If you have a vector of objects that you'd like to pass as if they were individual arguments, do it like so:

<set myvec=<vector 6 7 8/>>
          <join separator="WWW" _other_unkeyed=myvec/>
        </set>

"6WWW7WWW8"

<set myvec=<vector 6 7 8/>>
         5.<join separator="WWW" _other_unkeyed=myvec/>
        </set>

"5WWW6WWW7WWW8"

You can even use the subject and _other_unkeyed to concatenate the elements of two vectors together.

<set myvec=<vector 6 7 8/>>
         <vector 4 5/>.<join separator="WWW" _other_unkeyed=myvec/>
        </set>

"4WWW5WWW6WWW7WWW8"