Difference between revisions of "JoinText"
m
Line 4: Line 4:
 
[[Category:Text Functions]]
 
[[Category:Text Functions]]
  
−
= JoinText( A, I'', separator, finalSeparator, default, textForNull'' ) =
+
=== JoinText(a, i'', separator, finalSeparator, default, textForNull'' ) ===
  
−
Returns the elements of «A» (as text) concatenated along «I».
+
Returns the elements of array «a» as text concatenated over index «i».
  
 
If any elements are numeric, they are converted to strings using the number format settings for the current node.
 
If any elements are numeric, they are converted to strings using the number format settings for the current node.
Line 12: Line 12:
 
[[Null]] items are ignored, unless «textForNull» is specified.
 
[[Null]] items are ignored, unless «textForNull» is specified.
  
−
=== Optional parameters ===
+
==== Optional parameters ====
  
 
{| border="0"
 
{| border="0"
Line 25: Line 25:
 
! align="left" |
 
! align="left" |
 
* «default»  
 
* «default»  
−
| : || ''(new in 4.4.3)'' The result value when there are no items to be joined.  E.g., when all items are [[Null]].
+
| : || The result value when there are no items to be joined.  E.g., when all items are [[Null]].
 
|-
 
|-
 
! align="left" |
 
! align="left" |
 
* «textForNull»  
 
* «textForNull»  
−
| : || ''(new in 4.4.3)'' When specified, [[Null]] items are not ignored, and the text provided is used.
+
| : || When specified, [[Null]] items are not ignored, and the text provided is used.
 
|}
 
|}
  
−
= Examples =
+
==== Example ====
  
−
Suppose ''A'' is the following array, indexed by ''J''
+
Suppose ''A'' is this array, indexed by ''J''
 
::{| border="1"
 
::{| border="1"
 
! J → || 1 || 2 || 3 || 4 || 5
 
! J → || 1 || 2 || 3 || 4 || 5
Line 59: Line 59:
 
</code>
 
</code>
  
−
'''Treatment of Null'''.  Suppose ''B' is the following array indexed by ''J''
+
'''Treatment of Null'''.  Suppose '''''B''' is this array indexed by '''''J'''''
 
::{| border="1"
 
::{| border="1"
 
! J &rarr; || 1 || 2 || 3 || 4 || 5
 
! J &rarr; || 1 || 2 || 3 || 4 || 5
Line 92: Line 92:
 
</code>
 
</code>
  
−
= Notes =
+
=== Notes ===
  
−
=== The All-Null case ===
+
==== 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.
+
If all values in  «a» are [[Null]], or «a» has zero items, the result 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 text, which is often convenient.
  
 
We'd like to change this to be consistent, but are reluctant to do so because of backward compatibility.
 
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.  This parameter requires to patch release 4.4.3 or later.  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.
+
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 array «a» does not contain «null» values and always has a length of at least 1, 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:
+
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>
 
:<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.
 
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 =
+
==== See Also ====
  
 
* [[SplitText]]
 
* [[SplitText]]
 
* [[Text Concatenation Operator: &]]
 
* [[Text Concatenation Operator: &]]

Revision as of 20:40, 2 September 2015


JoinText(a, i, separator, finalSeparator, default, textForNull )

Returns the elements of array «a» as text concatenated over index «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»
 : The result value when there are no items to be joined. E.g., when all items are Null.
  • «textForNull»
 : When specified, Null items are not ignored, and the text provided is used.

Example

Suppose A is this 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 this 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

If all values in «a» are Null, or «a» has zero items, the result 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 text, which is often 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 array «a» does not contain «null» values and always has a length of at least 1, 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

Comments


You are not allowed to post comments.