Revision as of 17:12, 4 July 2012

JoinText( A, I, separator, finalSeparator, default, textForNull )

Returns the elements of «A» (as text) concatenated along «I».

If any elements are numeric, they are converted to strings using the number format settings for the current node.

Null items are ignored, unless «textForNull» is specified.

Optional parameters

«separator»	:	text inserted between each item.
«finalSeparator»	:	Used instead of «separator» between the penultimate and final items.
«default»	:	(new in 4.4.3) The result value when there are no items to be joined. E.g., when all items are Null.
«textForNull»	:	(new in 4.4.3) When specified, Null items are not ignored, and the text provided is used.

Examples

Suppose A is the following array, indexed by J

J →	1	2	3	4	5
	"one"	"two"	"three"	"four"	"five"

Then:



JoinText(A,J)

→
"onetwothreefourfive"


JoinText(A,J,',')

→
"one,two,three,four,five"


JoinText(A,J,", "," and ")

→
"one, two, three, four and five"


JoinText(Exp(J^2),J,', ')

→
"2.718, 54.6, 8103, 8.886M, 72G"

Treatment of Null. Suppose B' is the following array indexed by J

J →	1	2	3	4	5
	"one"	«null»	"three"	«null»	"five"



JoinText(B,J,",")

→
"one,three,five"


JoinText(B,J,",",textForNull:"")

→
"one,,three,,five"


JoinText(B,J,",",textForNull:"NULL")

→
"one,NULL,three,NULL,five"


JoinText([Null,Null,Null])

→
""


JoinText([Null,Null,Null],default:null)

→
«null»


JoinText([])

→
""


JoinText([],default:"empty")

→
"empty"

Notes

The All-Null case

The result when all items are Null, or when «A» has zero items, is the empty text, "". This is not consistent with the general Analytica convention that the result of an array function should be «null» when there are no non-null items in the array. It does mean that the result is always textual, which can also be convenient.

We'd like to change this to be consistent, but are reluctant to do so because of backward compatibility.

Instead of relying on this, we recommend that you make use of the «default» parameter to specify the behavior explicitly. By doing so, you'll be immune to any change to this default behavior. If you want it returning «null», then specify default:null. If you want it returning the empty text, then specify default:"". If your «A» array does not contain «null» values and always has a length of at least 1, then you don't have to worry about this.

If you want to concatenate all elements in a 2-D array, ignoring all «null» cells, then you'll want to use default:null, e.g:

JoinText(JoinText(A,I,",",default:null),J,",",default:null)

If you don't use default:null in this case, you'll get an extra comma when an all-null row appears.

See Also

SplitText
Text Concatenation Operator: &

@@ Line 91: / Line 91: @@
 |}
 </code>
+= Notes =
+=== The All-Null case ===
+The result when all items are [[Null]], or when «A» has zero items, is the empty text, <code>""<code>.  This is not consistent with the general Analytica convention that the result of an array function should be [[«null»]] when there are no non-null items in the array.  It does mean that the result is always textual, which can also be convenient.
+We'd like to change this to be consistent, but are reluctant to do so because of backward compatibility.
+Instead of relying on this, we recommend that you make use of the «default» parameter to specify the behavior explicitly.  By doing so, you'll be immune to any change to this default behavior.  If you want it returning «null», then specify <code>default:null</code>.  If you want it returning the empty text, then specify <code>default:""</code>. If your «A» array does not contain «null» values and always has a length of at least 1, then you don't have to worry about this.
+If you want to concatenate all elements in a 2-D array, ignoring all «null» cells, then you'll want to use <code>default:null</code>, e.g:
+:<code>[[JoinText]]([[JoinText]](A,I,",",default:null),J,",",default:null)</code>
+If you don't use <code>default:null</code> in this case, you'll get an extra comma when an all-null row appears.
 = See Also =

Difference between revisions of "JoinText"