Analytica Docs - User contributions [en]

File:AcceptanceTestFiles.png

2025-11-19T03:56:58Z

Fredbrunt:

CumMin and CumMax

2025-06-03T06:11:34Z

Fredbrunt: /* PassNull */ fixed minor error in example

''New to [[Analytica 5.3]]''

[[Category:Transforming functions]]

{{ReleaseBar}}

== CumMin(x, I'', passNull, reset{{Release|5.5||, window}}'') ==
== CumMax(x, I '', passNull, reset{{Release|5.5||, window}}'') ==

Returns an array with each element being the minimum or maximum of all preceding elements of «X» along dimension «I» up to, and including, the corresponding element of «X».

== Examples ==
:<code>I := </code>
::<code>1..7</code>
:<code>X := </code>
::<code>Array(I, [5, 2, 1, 8, -3, 0, 4])</code>
:<code>CumMin(X, I) →</code>
::<code>[5, 2, 1, 1, -3, -3, -3]</code> {indexed by <code>I</code>}
:<code>CumMax(X, I) →</code>
::<code>[5, 5, 5, 8, 8, 8, 8]</code> {indexed by <code>I</code>}

== Optional Parameters ==
=== PassNull ===
«PassNull» is an optional boolean parameter that defaults to <code>False</code>. When it is omitted or explicitly set to <code>False</code>, [[CumProduct]] ignores [[Null]] values. In that case they have essentially the same effect as a one, unless they happen to be the first value in «X», in which case they are passed since no numeric values are yet obtained.

When «passNull» is explicitly set to true, then [[Null]] values are passed through as [[Null]] in the result.

:<code> J := 1..11</code>
:<code>X2 := </code>
::<code>Array(J, [Null, Null, 4, 2, Null, Null, 2, -1, 3, 2, Null])</code>
:<code>CumMin(X2, J) →</code>
::<code>[Null, Null, 4, 2, 2, 2, 2, -1, -1, -1, -1]</code> { Indexed by <code>J</code> }
:<code>CumMin(X2, J, passNull: false) →</code>
::<code>[Null, Null, 4, 2, 2, 2, 2, -1, -1, -1, -1]</code> { Indexed by <code>J</code> }
:<code>CumMin(X2, J, passNull: true) →</code>
::<code>[Null, Null, 4, 2, Null, Null, 2, -1, -1, -1, Null]</code> { Indexed by <code>J</code> }
:<code>CumMax(X2, J, passNull: true) →</code>
::<code>[Null, Null, 4, 4, Null, Null, 4, 4, 4, 4, Null]</code> { Indexed by <code>J</code> }

=== Reset ===
The optional «reset» parameter accepts an array of boolean values indexed by «I». At the positions where «reset» is true, [[CumMin]] or [[CumMax]] starts over.

:<code>I := </code>
::<code>[1, 2, 3, 4, 5, 6, 7]</code>
:<code>X := </code>
::<code>Array(I, [5, 2, 1, 8, -3, 7, 5])</code>
:<code>R := </code>
::<code>Array(I, [0, 0, 1, 0, 0, 1, 0])</code>
:<code>CumMin(X, I, reset: R) →</code>
::<code>[5, 2, 1, 1, -3, 7, 5]</code> { Indexed by <code>I</code> }
:<code>CumMax(X, I, reset: R) →</code>
::<code>[5, 5, 1, 8, 8, 7, 7]</code> { Indexed by <code>I</code> }

«Reset» can be used to restart the progressive min or max each time some state change occurs. In such a scenario, the «reset» parameter is set to <code>True</code> at the first instant (along «I») that the system is in the new state.

=== Window ===
''New to [[Analytica 6.0]]''

When «window» is specified as a positive integer, does a windowed cum min or cum max. In other words, returns the minimum (or maximum) value among the most recent «window» points.

== See Also ==
* [[Min]], [[Max]]
* [[Cumulate]], [[CumProduct]]
* [[Dynamic]]

Product

2025-05-22T14:26:29Z

Fredbrunt: /* Examples */ Minor fix to example con't

[[Category:Array-reducing functions]]
[[Category:Doc Status C]] 

== Product(X, I) ==

Returns the product of all of the elements of «X», along the dimension indexed by «I».

[[Syntax]]:
:[[Product]](X: Array[I]; I: Index)

== Examples ==
:<code>Index I := 1..10</code>
:<code>Product(1 + 1/I, I) → 11</code>

== See Also ==
* [[CumProduct]]
* [[ProductLog]]
* [[Sum]]
* [[Array-reducing functions]]

Product

2025-05-22T05:29:50Z

Fredbrunt: /* Examples */

[[Category:Array-reducing functions]]
[[Category:Doc Status C]] 

== Product(X, I) ==

Returns the product of all of the elements of «X», along the dimension indexed by «I».

[[Syntax]]:
:[[Product]](X: Array[I]; I: Index)

== Examples ==
:<code>Index I := 1..10</code>
:<code>Product(1 + 1/I, J) → 11</code>

== See Also ==
* [[CumProduct]]
* [[ProductLog]]
* [[Sum]]
* [[Array-reducing functions]]

Subscript-Slice Operator

2025-05-08T07:11:33Z

Fredbrunt: /* Subscripting and Meta-Inference */ Changing 'Var' to 'Local'

[[category:Operators]]
[[Category:Doc Status C]] 

__TOC__

The '''subscript''' operation, in square brackets after an expression «X»,
:<code>X[I = v]</code>

returns the element of array «X» for which index «I» equals value «v». It's like subscripting in many other computer languages, but a lot more powerful because of Analytica's Intelligent Arrays features.

If «X» has more indexes than «I», this expression returns the [[slice]] (or subarray) of «X» for which ''I = v''. The resulting [[slice]] is indexed by the other Index(es) of «X».

Subscript also works if v is an array, returning an array of all the slices of «X» for which ''I = v''. The result is indexed by the Index(es) of «v», as well as any Index(es) of «X» other than «I». You can use this feature to subset, sort, or reindex an Array, as described below.

The '''slice''' operator X[@I = n] returns the slice of array «X» for the nth element of index «I». [[Slice]] is the same as [[Subscript]], except that you put '@', the '''positional''' operator, before the Index «I». So it treats Index «I» as a list of ''positions'' -- i.e. integers ''1'' to ''m'', where ''m = Size(I)''.

You can subscript or slice over multiple indexes together, for example:
:<code>X[I = v, J = u]</code>

which returns the element (or slice) of «X» over indexes «I» and «J».

Subscript operator can work over an expression as well as a variable name, for example:
:<code>Sum(Y, J)[K = 2]</code>

gives the slice of the sum of <code>Y</code> over index <code>J</code> for which <code>K = 2</code>. It is equivalent to:
:<code>Sum(Y[K = 2], J)</code>

If no element of «I» matches the value of «v» for subscript, it returns [[Null]] and a warning message (unless turned you turn off that warning).

== Naming Indexes ==

In Analytica, you must name the Index(es) over which you are subscripting, e.g.
:<code>X[I = 1, J = 'B']</code>

Other computer languages don't expect names in subscripts. They require you to list the indexes in the sequence used in their internal array representation:
:<code>X[1, 'B']</code>

The advantages of identifying indexes by name, as in Analytica, include:
# you don't need to know or care about the sequence of the indexes in the array representation -- unlike spreadsheets, and most general languages, which need to you to know which index refers to rows, columns, or higher dimensions. In Analytica, it is your choice when displaying an array which index to show over the rows and columns; not something inherent in the underlying representation.
# you can list Index(es) in any sequence, ignoring any other Index(es) that the array may have. As you develop an Analytica model, or perform scenario or sensitivity analysis, it is common to add further indexes. Expressions using subscripts with named indexes are robust to such changes in the model, unlike conventional languages in which they break.

Naming indexes in subscripts is similar to the named parameter syntax available in Analytica for calling functions: You can specify names for each parameter and don't need to worry about their sequence or omitting unneeded optional parameters -- e.g.
:<code>FindInText(', ', text: X, caseInsensitive: True, repeat: True)</code>

The difference is that naming indexes in subscripts is required, where naming parameters in function calls is optional as long as you insert all parameters in the standard sequence.

== Implicit Indexing -- subscripting over an irrelevant index ==

If you Subscript (or Slice) an array «X» over an Index «I» that is not actually an index of «X», it simply returns the value of «X» unchanged. This is with Analytica's fundamental principle of of implicit indexing: If «X» is not explicitly indexed by Index «I», it is assumed to have the same value for each value of «I».

For example, suppose variable <code>Markup</code> is the percentage mark-up applied by a retailer to each product line it sells. If it applies the same mark-up to all products, it can set <code>Markup</code> to a single percentage. If it wants to apply different <code>Markup</code>'s to different product Categories or at stores in different Locations, it can define <code>Markup</code> as an Array indexed by <code>Categories</code> and <code>Locations</code>. If <code>Markup</code> does not vary over time, then it need not be indexed by <code>Time</code> (or <code>Month</code> or <code>Year</code>) -- i.e. <code>Markup[Year = 2014]</code> would have the same value for any value of Year because it isn't indexed by Year.

== Positional and Associational indexing ==

The standard subscript operation, without the '@', uses ''associational'' indexing: It identifies the value of index «I» by association with the value or label of each element of the Index. The slice operator, with the '@', uses ''positional'' indexing. It identifies each slice by its position in index «I», an integer from ''1'' to ''m'', where ''m = Size(I)''.

Usually, it is wisest to make sure that the values of an Index are unique, but occasionally you must use an Index that contains repeated values. If Index <code>Name</code> contains the last name of all employees, some employees may have the same last name. In that case, subscripting by <code>Name</code> may be ambiguous:
:<code>Salary[Name = 'Smith']</code>

will return the salary of the first person named <code>Smith</code>. In such cases, you can use positional indexing to select a slice for the person you want.
:<code>Salary[@Name = 42]</code>

This assumes you know the ID (number in the <code>Name</code> index) for each person.

For more, see [[Associative vs. Positional Indexing]].

== Subscript(x, i, v) and Slice(x, i, v) functions ==

The functions [[Subscript]](x, i, v) and [[Slice]](x, i, v) are exactly equivalent to ''x[i = v]'' and ''x[@i = v] respectively.
They exist mostly for forward compatibility from the earliest releases of Analytica that did not include the operator syntax.

== Subscripts and Array Abstraction ==

When «x» or «n» is atomic, the slice/subscript operations usually reduce the dimensionality of the array by one dimension (the exception being when the index is not a dimension of the original value). However, in general, «x» or n can be arbitrary expressions, and the result of «x» or «n» may be array-valued. In general, dimensions appearing in «x» or «n» will appear in the result, so the dimensionality may actually increase as a result of applying the slice or subscript operators.

As [[array abstraction]] operates over the «x» and «n» parameters, the [[slice]] and [[subscript]] operators offer extremely general and powerful lookup operators. Fairly complex operations equivalent to re-indexing, VLookup operations in spreadsheets, outer-joins in relational databases, and others are achieved quite simply and directly using subscript or slice operations. These operators are also used for sorting or re-ordering arrays, filtering rows, and other operations. This flexibility relieves Analytica from having to have a plethora of lookup functions often found in many other languages. However, mastering the full power of Slice and Subscript operators may take some time.

=== Re-indexing ===
Re-indexing is a common operation -- replace one index of an array by another index. If indexes <code>I</code> and <code>J</code> have the same elements in the same order with no duplicates, which might arise if <code>J</code> is defined as:
:<code>J := CopyIndex(I)</code>

This simple expression re-indexes as you want, if array <code>A</code> is indexed by <code>I</code>:
:<code>A[I = J]</code>

The result is identical to <code>A</code>, except that it is indexed by <code>J</code> instead of <code>I</code>.

You can do the same using the positional operator:
:<code>A[@I = @J]</code>

The advantage of this is that it works if <code>I</code> and <code>J</code> are the same length but have different elements, or if the indexes contain duplicate elements.

Here is an example, to compute the outer-product of a vector, <code>V</code> indexed by <code>I</code> with its transpose:

:<code>Index J := CopyIndex(I)</code> -- creates <code>J</code> with identical length and values to <code>I</code>.
:<code>V * V[I = J]</code>

The result is the outer product, with dimensions <code>I</code> x <code>J</code>.

=== Re-ordering ===

The slice and subscript operators can be used to re-order an array in various scenarios. Often, you will have an index <code>J</code>, which is a permutation of index <code>I</code>. In this case, a re-indexing re-orders the elements of <code>A</code>, using just <code>A[I = J]</code>.

A common example of this is sorting. Suppose <code>Row</code> and <code>Col</code> are both indexes of array <code>A</code>, and you want to sort on the column <code>A[Col = 'ROI']</code>. Here you would create a new index, <code>SortedRow</code>, defined as
:<code>SortIndex(A[Col = 'ROI'])</code>

and then compute the sorted array using <code>A[Row = SortedRow]</code>.

Another example of re-ordering is the reversing of elements. In Analytica, the [[Dynamic]] function computes starting from the beginning of [[Time]]. In many dynamic programming applications, we would like to start from the final time point and work our way back. Often the way this is done is by reversing the the array so that we can use [[Dynamic]], and then reversing the result once computed. This is one example where reversing an array is useful. To reverse an array, the Slice operator is the most convenient:
:<code> A[@I=size(I) - @I + 1]</code>

It's often useful to shift an array left or right along a given index. The basic form of a shift-left or shift-right is <code>A[@I = @I - 1]</code> or <code>A[@I = @I + 1]</code> respectively. See the "out of range conditions" section below for how to handle the rightmost or leftmost element of the result, which otherwise end us as [[Null]].

=== Filtering ===

Filtering extracts a subset of "rows" from an array along a given dimension. If we want a subset of slices along dimension <code>I</code>, we need to define a new index, say <code>I2</code>, containing a subset of <code>I</code>. For example, to obtain the subset of people younger than 30, a subset of the <code>People</code> index, we define the new index, <code>YoungPeople</code>, and use it in the [[Subscript]]:
:<code>Index YoungPeople := Subset(PersonData[Trait = 'Age'] < 30)</code>
:<code>PersonData[People = YoungPeople]</code>

=== Multi-step lookup, outer-join, or VLookup ===

We often need to combine two arrays with different indexes, where one array contains values associated with elements of the other array. This combination is called an "outer join" for databases or''' VLookup''' (or '''HLookup''') in Excel. For example, suppose we want to obtain the salary of each <code>Person</code>, given the array, <code>Salary_by_profession</code>, with the salary for each <code>Profession</code> and another array, <code>Profession_by_person</code>, with the <code>Profession</code> for each <code>Person</code>:

:{| border="0"
|
{| class="wikitable"
! Profession !! Salary_by_profession
|-
| 'Dock loader' || $45,000
|-
| 'Crane operator' || $75,000
|-
| 'Forklift driver' || $32,000
|-
|}
|        ||
{| class="wikitable"
! Person !! Profession_by_person
|-
| 'Joe Smith' || 'Crane operator'
|-
| 'Mark Jones' || 'Forklift driver'
|-
| 'Greg Johnson' || 'Forklift driver'
|-
|}
|}

In Analytica, we can compute the salary by person with this simple [[Subscript]] expression:

:<code>Salary_by_profession[Profession = Profession_by_person]</code>

The result is:

:{| class="wikitable"
! Person !! Salary_by_person
|-
| 'Joe Smith' || $75,000
|-
| 'Mark Jones' || $32,000
|-
| 'Greg Johnson || $32,000
|-
|}

=== When a subscript is Out of Range ===

If you evaluate
:<code>A[I = x]</code>

when x is not an element of I, or
:<code>A[@I = n]</code>

when n is not a valid position of I (e.g., ''n < 0'' or ''n > size(I)''), the result is "out of range" and usually returns [[Null]]. If the [[Null]] will appear in the result, it usually gives an "Out of range" warning. You can switch off this warning in two ways: You can unset the default preference in [[Preferences|"Show Result Warnings" preference]],
or you can enclose the expression in the [[IgnoreWarnings]]() function
:<code>IgnoreWarnings(A[@I = @I - 1])</code>

It is generally better to wrap the expression with the [[IgnoreWarnings]] function: It runs faster as a result of relieving Analytica from having to track whether the out-of-range condition impacts the final result.

== Subscript Assignment ==

You may assign a value to a Subscripted element of a local variable using either the subscript (or slice) operator on the left-hand side of the := operator. For example:
:<code>v[Time = 5] := 0</code>

When using Subscript assignment, the variable being assigned to MUST be local, even if used from an [[OnChange]] expression (or Button [[script]]). (See [[Assignment Operator:: ::=#Don't change a global index used by a transient array|Assignment Operator :: ::]] for why you can't usually assign to a Global variable.)

Subscript assignment does array abstraction in the usual ways. In expressions
:<code>V[I = x] := y</code>
:<code>V[@I = n] := y</code>

any of the parameters «V», «x», «n», and «y» may be arrays with one or multiple Indexes. If local variable «V» is not indexed by «I» before the assignment, it will be after the assignment. Any slices for which ''I <> x'' (or ''@I <> n'') will contain the same value(s) as «V» did before the assignment -- consistent with the Principle of Implicit Indexing. Only the assigned slice ''V[I = x]'' gets the new value, «y».
If «y» has an Index (or Indexes) not already in «V», «V» will gain that Index (those Indexes) during the assignment. Again, each slice of «V» for which ''I <> x'' will have the original values of «V» repeated over the new Index(es) of «y».

For example, suppose «V» is indexed only by «I», but «y» contains the index «J». Then after evaluating
:<code>V[I = x] := y</code>

«V» will be indexed by both «I» and «J». The slice corresponding to ''I = x'' will have a potentially different value for each element of «J», but the other slices along «I» will be constant across «J» (having the original value of «v»).

== Subscripting and Meta-Inference ==

[[Meta-Inference]] is an advanced Analytica programming topic concerning computation about the objects and structure of the model itself. For example, it may compute the number of input variables, or find the common inputs of two variables. Meta-inference must handle the situation when an index contains object identifiers or expressions as elements. The default behavior of [[Subscript]] requires these variables and expressions to be evaluated, and for those that evaluate to scalars, both the scalar value and the original [[varTerm]] or expression are recognized by [[Subscript]]. This is demonstrated by the following example:

:<code>Variable A := 5</code>
:<code>Variable B := 10</code>
:<code>Index I := [ A, B ] { Global index, defined as List, with identifier A and B in each cell }</code>
:<code>Variable C := Table(I)(3, 4)</code>

:<code>C[I = 5] → 3</code>
:<code>C[I = A] → 3</code>
:<code>C[I = VarTerm(A)] → 3</code>
:<code>IndexValue(I) → [A, B] { These are [[VarTerm]]s -- handles to objects }</code>

There is a distinct difference between the first two subscript examples and the third. <code> C[I = 5]</code> and <code>C[I = A]</code> are performing associative lookup based on the evaluated result of the index elements, while <code>C[I = VarTerm(A)]</code> is using the raw un-evaluated [[IndexValue]].

When your intention is to reason about the structure of the objects in the model, the default functionality of subscript has a couple undesirable aspects. First, it forces the elements of the index to be evaluated. If those computations are expensive, they must be carried out before your meta-inference can proceed, and if there are errors or warnings while evaluating, those errors appear. Second, if some elements evaluate to [[varTerm]]s, there may be ambiguities.

The following example demonstrates these concerns. The example collects the definition (e.g., for a report) of all the objects with definitions in module <code>Report_A</code>.

:<code>Index allObjects := Contains of Report_A;</code>
:<code>Local v := allObjects;</code>
:<code>Local allTitles := Title of v;</code>
:<code>Local allDefns := Definition of v;</code>
:<code>Index Objects_With_Defs := Subset(not IsUndef(allTitles));</code>
:<code>allDefns[allObjects = Objects_with_Defs]</code>

When the subscript operation in the last line is evaluated, all the objects listed in the <code>Objects</code> index will need to be fully evaluated. If a variable in <code>Module Report_A</code> contains an error, the error will appear when the last line is evaluated. If a variable takes 5 hours to compute, this expression will trigger and wait for that computation, even though the result is not really needed here.

To avoid these problems, you must tell Analytica to treat the <code>allObjects</code> index as a meta-index, i.e., as an index containing literal expressions or identifiers, whose raw unevaluated values are to be used in associative lookup, but whose evaluated element values are not to be used. This is done by changing the first line to:

:<code>[[MetaIndex]] allObjects := Contains of Report_A;</code>
:...

For a global index object, to achieve this treatment, you must set the [[MetaOnly]] attribute to 1 (true), see [[MetaOnly]] for instructions. In the previous example, when the [[MetaOnly]] attribute set to true for Index <code>I</code>, the previous expressions evaluate as

:<code>C[I = 5] → Null { not found }</code>
:<code>C[I = A] → Null { not found }</code>
:<code>C[I = VarTerm(A)] → 3</code>

With [[MetaOnly]] set, index elements containing system variables such as INF, [[Null]], True, False, Pi, etc., will not match to the underlying value, since these are actually system variable objects. See [[MetaOnly]] for more details.

== See Also ==

* [[Subscript]] function
* [[Slice]] function
* [[Index Position Operator::@]]
* [[SortIndex]]
* [[Rank]]
* [[Subscript]]
* [[IgnoreWarnings]]
* [[Associative vs. Positional Indexing]]
* [[Assignment Operator:: ::=]]
* [[IdentPred]]

Slice

2025-05-07T07:47:46Z

Fredbrunt: /* Examples */ Fixed out of range example, before it wasn't returning null

[[Category:Functions that select part of an array]]

== Slice(A, I, n) ==

Returns the «n»th slice of array «A» along index «I».

The [[Slice]] function is so commonly used, as is its associational counterpart, the [[Subscript]] function, that a special shorthand notation is more often used in Analytica expressions. <code>Slice(A, I, n)</code> can be written as [[Subscript-Slice Operator|A[@I = n]]].

== Slice(A, n) ==

When «A» is one-dimensional, «I» can be omitted. Use this syntax when you want to obtain the «n»th element of a list, but cannot name the index since it is implicit.

== Library ==

Array functions

== Examples ==
:<code>Index I := [10, 20, 30, 40]</code>
:<code>Index J := ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']</code>
:<code>Index K := 1..3</code>
:<code>Variable A := Table(J)(9, 2, 3, 4, 1, 9, 0, 3)</code>
:<code>Variable B := I + K</code>

:<code>Slice(A, J, 5) → 1</code>
:<code>Slice(A, J, 3..6) → [3, 4, 1, 9]</code>
:<code>Slice(A, J, K) → Array(J, [9, 2, 3])</code>
:<code>Slice(A, J, 9) → «null» {with an out-of-range warning}</code>
:<code>Slice(A, I, 3) → Array(J, [9, 2, 3, 4, 1, 9, 0, 3])</code>

:<code>Slice(B, I, 3) → Array(K,[31, 32, 33])</code>
:<code>Slice(B, K, 3) → Array(I,[13, 23, 33, 43])</code>

:<code>Slice(4, J, 5) → 4</code>

== See Also ==
* [[Arrays and Indexes]]
* [[Slice assignment]]
* [[Subscript-Slice Operator]]
* [[Subscript]]
* [[Subscript and slice of a subarray]]
* [[Table Splicing]]

Mod

2025-04-29T03:03:36Z

Fredbrunt: /* IsInteger */ Change incorrect "==" operator to "="

[[category:Math Functions]]
[[Category:Doc Status C]] 

==Mod(x, y'', pos'')==

The remainder (modulus) of «x» / «y».

The sign of the result of <code>Mod(x,y)</code> is the same as the sign of «x» -- i.e., if «x» is negative, then so is the result. The sign of «y» does not impact the sign of the result. This variation is the same convention used by the corresponding operator in C/C++ (ISO 1999), C#, Java, PHP, Visual Basic, AMPL and many other languages. Some languages, including MATLAB, Lisp, Fortran, and Ada, have two different modulo operators, with one corresponding to this convention. The modulo operator in a few other languages, including Mathematica, R and Excel, do not follow this convention (these use the sign of the denominator).

You can specify «pos» as true to force the result to be non-negative, in the range <code>0 ≤ Mod(x,y) < Abs(y)</code>. As «x» increases through all negative and positive numbers, the result cycles through this range.

<code>Mod(x,1)</code> extracts the fractional portion of a number.

==Examples ==

:<code>Mod(20,7) → 6</code>
:<code>Mod(-20,7) → -6</code>
:<code>Mod(-20,-7) → -6</code>
:<code>Mod(20,-7) → 6</code>
:<code>Mod(-20,7,pos: true) → 1</code>
:<code>Mod(Pi,1) → 0.141592653589793</code>

== Special uses ==

=== IsOdd and IsEven ===

To test whether an integer <code>x</code> is odd use <code>Mod(x, 2) = 1</code>, and similarly, to test whether an integer is even use <code>Mod(x, 2) = 0</code>.

=== IsInteger ===

To test whether a number <code>x</code> is an integer, use <code>Mod(x,1) = 0</code>

=== The fractional part of a number ===
:<code>[[Mod]]( Pi, 1)</code> → 0.141592653589793
:<code>[[Mod]]( -Pi,1)</code> → -0.141592653589793

=== Time part of a date-time number ===

(''new in [[Analytica 6.0]]'') When you have a date-time number, <code>[[Mod]](d,1)</code> returns the time part and returns it as a date-time number instead of a float.

==See Also==
* [[Abs]]
* [[GCD]]
* [[IsNumber]]
* [[Array Abstraction]]
* [[Math functions]]

Mod

2025-04-29T03:03:15Z

Fredbrunt: /* IsOdd and IsEven */ Change incorrect "==" operator to "="

[[category:Math Functions]]
[[Category:Doc Status C]] 

==Mod(x, y'', pos'')==

The remainder (modulus) of «x» / «y».

The sign of the result of <code>Mod(x,y)</code> is the same as the sign of «x» -- i.e., if «x» is negative, then so is the result. The sign of «y» does not impact the sign of the result. This variation is the same convention used by the corresponding operator in C/C++ (ISO 1999), C#, Java, PHP, Visual Basic, AMPL and many other languages. Some languages, including MATLAB, Lisp, Fortran, and Ada, have two different modulo operators, with one corresponding to this convention. The modulo operator in a few other languages, including Mathematica, R and Excel, do not follow this convention (these use the sign of the denominator).

You can specify «pos» as true to force the result to be non-negative, in the range <code>0 ≤ Mod(x,y) < Abs(y)</code>. As «x» increases through all negative and positive numbers, the result cycles through this range.

<code>Mod(x,1)</code> extracts the fractional portion of a number.

==Examples ==

:<code>Mod(20,7) → 6</code>
:<code>Mod(-20,7) → -6</code>
:<code>Mod(-20,-7) → -6</code>
:<code>Mod(20,-7) → 6</code>
:<code>Mod(-20,7,pos: true) → 1</code>
:<code>Mod(Pi,1) → 0.141592653589793</code>

== Special uses ==

=== IsOdd and IsEven ===

To test whether an integer <code>x</code> is odd use <code>Mod(x, 2) = 1</code>, and similarly, to test whether an integer is even use <code>Mod(x, 2) = 0</code>.

=== IsInteger ===

To test whether a number <code>x</code> is an integer, use <code>Mod(x,1) == 0</code>

=== The fractional part of a number ===
:<code>[[Mod]]( Pi, 1)</code> → 0.141592653589793
:<code>[[Mod]]( -Pi,1)</code> → -0.141592653589793

=== Time part of a date-time number ===

(''new in [[Analytica 6.0]]'') When you have a date-time number, <code>[[Mod]](d,1)</code> returns the time part and returns it as a date-time number instead of a float.

==See Also==
* [[Abs]]
* [[GCD]]
* [[IsNumber]]
* [[Array Abstraction]]
* [[Math functions]]

Ceil

2025-04-23T05:29:55Z

Fredbrunt: /* Ceil(x, digits, dateUnit) */ fixed type, change comma to period

[[category:Math Functions]]
[[Category:Doc Status C]] 

== Ceil(x'', digits, dateUnit'') ==

[[Ceil]](x) returns the smallest integer that is greater than or equal to «x».

:<code>Ceil(174.001) → 175</code>
:<code>Ceil(-89.95) → -89</code>

When the optional «digits» parameter is given, cuts the number off at «digits» to the right of the decimal, returning the smallest multiple of 10<sup>-«digits»</sup> that is equal to or larger than «x».

:<code>Ceil( 3.141592, 2) → 3.150000</code>
:<code>Ceil(-3.141592, 2) → -3.140000</code>
:<code>Ceil( 3.141592, 5) → 3.141600</code>

«digits» may also be negative, in which case the least significant -«digits» digits will be '0':

:<code>Ceil(123456.789, -1) → 123460.00</code>
:<code>Ceil(123456.789, -4) → 130000.00</code>

If you specify the «dateUnit» parameter, [[Ceil]] rounds a date-time number upward to the earliest date-time at the «dateUnit» increment that is equal to or comes after the date-time specified in «x». For example, you can round up to the beginning of the following year, quarter, or month, or to the beginning (meaning midnight) of the next weekday, day, or up to the next hour, minute or second. The value you pass to «dateUnit» must be one of the following: 'Y', 'year', 'Q', 'quarter', 'M', 'month', 'WD', 'weekday', 'D', 'day', 'h', 'hour', 'm', 'minute', 's', or 'second'. Note that 'M' (for Month) and 'm' (for minute) are case sensitive.

:<code>Ceil(MakeDate(2010, 8, 8), dateUnit: 'Y') → 2011-Jan-1</code>
:<code>Ceil(MakeDate(2010, 8, 8), dateUnit: 'Q') → 2010-Oct-1</code>
:<code>Ceil(MakeDate(2010, 8, 8), dateUnit: 'M') → 2010-Sep-1</code>
:<code>Ceil(MakeDate(2010, 8, 1), dateUnit: 'M') → 2010-Aug-1</code>
:<code>Ceil(MakeDate(2010, 8, 1)+MakeTime(0, 0, 1), dateUnit: 'M') → 2010-Sep-1</code>

Notice in the last example that if we are even one second past midnight of Aug 1st, it rounds to the beginning of the next month.

== Number Format ==
The [[Ceil]], [[Round]] and [[Floor]] functions all cut a number off to the indicated number of decimal places, but note that this is separate from the number format used to display the number. The number format setting controls how many digits are shown when displaying numbers, such as in an edit or result table. For example, after rounding to 4 decimal places, a number may be 2.3456, but if your number format is set to fixed point with 2 digits, this would display as 2.35.

To see the full effect of the [[Ceil]] function, set the number format to a large number of digits.

== See Also ==
* [[Floor]]()
* [[Round]]()
* [[MakeDate]]()
* [[MakeTime]]()
* [[Sequence]]()
* [[DateAdd]]()
* [[DatePart]]()

Operators

2025-04-21T04:37:19Z

Fredbrunt: /* Scoping operator (::) */ Fixing example which is MISSING the scoping operator

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Expressions > {{PAGENAME}}</breadcrumbs>

An infix '''''operator '''''is a symbol, such as a plus sign (<code>1 + 2</code>) or product (<code>10*2</code>), that operates on the values before and after it. A prefix operator, such as unary minus (<code>-100</code>) operates only on the value after it. Analytica includes these fairly standard opera tors, including arithmetic, comparison, and logical operators:

=== Arithmetic operators ===
The arithmetic operators apply to [[numbers]] and produce numbers:
:{| class="wikitable"
!Operator
!Meaning
!Examples
|-
|x+y
|plus
|<math>3 + 2 → 5</math>
|-
|x - y
|binary minus
|<math>3 - 2 → 1</math>
|-
|<nowiki>-x</nowiki>
|unary minus
|<math>-2 → -2</math>
|-
|x*y
|product
|<math>3*2 → 6</math>
|-
|x/3 or x÷y
|division
|<math>3/2 (= \frac{3}{2}) → 1.5</math>
|-
|x^y
|to the power of
|<math>3^2 = 3^2 → 9</math>
<math>4^.5 = 4^{\frac{1}{2}} → 2</math>
|}

=== Text concatenation ===

The text concatenation operator, <code>&</code> joins the sequence of characters from each parameter to form a text result. If either parameter is not already text, then the value is ''coerced'' to text using the number format for the object containing the expression. If you use the operator in a [[user-defined function]] then the function's number format is used.

:{| class="wikitable"
!Operator
!Meaning
!Examples
|-
|a & b
|concatenate
|<code>'foo' & 'bar' → 'foobar'</code><br />
<code>'pi=' & Pi → 'pi=3.142'</code><br />
<code>(1/5) & (7^2) → '0.249' </code>
|}

The last two examples shown may be different when the current object's number format is different at the time the expression is evaluated. For example, when Fixed Point, 3 digits with trailing zeroes is used,
:<code>'pi=' & Pi → 'pi=3.14'</code>
:<code>(1/5) & (7^2) → '0.2049.00' </code>

When coercing numbers to text, you can instead use the [[NumberToText]] function, so that the number format actually used is explicit in the expression.
:<code>'pi=' & [[NumberToText]](Pi, 'Suffix', digits:15) → 'pi=3.14159265358979'</code>

=== Comparison operators ===

Comparison operators apply to [[numbers]] and [[text values]] and produce [[Boolean or truth values|Boolean values]].
:{| class="wikitable"
!Operator
!Meaning
!Examples
!→ (1 = true, 0 = false)
|-
|<
|less than
|<code> 2 < 2 </code>
<code> 'A' < 'B' </code>
|<code>→ 0</code>
<code>→ 1</code>
|-
|<=
|less than or equal to
|<code> 2 <= 2 </code>
<code>'ab' <= 'ab' </code>
|<code>→ 1</code>
<code>→ 1</code>
|-
|=
|equal to
|<code> 100 = 101 </code>
<code> 'AB' = 'ab' </code>
|<code>→ 0</code>
<code>→ 0</code>
|-
|>=
|greater than or equal to
|<code> 100 >= 1 </code>
<code>'ab'> = 'cd' </code>
|<code>→ 1</code>
<code>→ 0</code>
|-
|>
|greater than
|<code> 1 > 2 </code>
<code> 'A' > 'a' </code>
|<code>→ 0</code>
<code>→ 1</code>
|-
|<>
|not equal to
|<code>1 <> 2 </code>
<code>'A' <> 'B' </code>
|<code>→ 1</code>
<code>→ 1</code>
|}

=== Alphabetic ordering of text values ===

You can apply the comparison operators, <. >, >=, <=, or sorting functions, [[SortIndex]](d, i), [[Sort]](d, i) and [[Rank]](), to [[Text values|text values]]. They generally use alphabetical order as in a dictionary, so:
:<code>'Analytica' < 'Excel' → 1 (True)</code>
These operators and functions are normally case sensitive, so uppercase letters precede lowercase letters:
:<code>'Analytica' > 'excel' → 0 (False)</code>
If you want alphabetic ordering to ignore case, use [[TextUpperCase]]() or [[TextLowerCase]]() to convert all letters to the same case.
:<code>TextUpperCase('Analytica') < TextUpperCase('excel') → 1 (True)</code>
In functions, [[SortIndex]](d, i), [[Sort]](d, i) and [[Rank]](), you can set their optional parameter «caseInsensitive» to True if you want them to ignore case.

Usually, digits precede letters:
:<code>'9' < 'A' → 1 (True)</code>

The collation order of characters is region-specific collation, according to your language and country. It is determined by the <code>TextLocale</code> system variable. If you want to see or change the collation order, bring up the [[Object window]] for <code>TextLocale</code> by selecting it from the [[Definition menu|Definition]] → [[Definition menu (more)#System Variables submenu|System Variables submenu]], with nothing selected and while in edit mode.

In general, the ordering of text may be different from the ordering implied by the numeric ASCII codes of the characters. For example, <code>'de' < 'dé' < 'df'</code>, whereas the ASCII code for <code>'é'</code> comes after the ASCII code for <code>'f'</code>. If you want text comparisons to use simple ASCII ordering, you can set '''TextLocale''' to be <code>ANSI</code>.

When two [[text values]] do not contain identical character sequences, they are considered to be unequal, even if they represent the exact same text. This can happen in Unicode with combining characters. For example, an accented 'é' can be either <code>Chr(233)</code> or <code>Chr(769)&'e'</code>, where the Unicode <code>Chr(769)</code> is the combining acute accent, which modifies the character that follows. Although these alternate representations of <code>'é'</code> are non-equal, they will have the same inequality comparisons with all other text, as if they are as closely adjacent in the sort order as is possible.

=== Logical operators ===

Logical operators apply to [[Boolean or truth values|Boolean values]] and produce Boolean values.

:{| class="wikitable"
!Operator
!Meaning
!Examples
!
|-
|<code>''b1'' AND ''b2''</code>
|true if both ''<code>b1</code>'' and ''<code>b2</code>'' are true,
otherwise false
|<code>5 > 0 AND 5 > 10</code>
|<code>→</code> <code>False</code>
|-
|<code>''b1'' OR ''b2''</code>
|true if ''<code>b1</code>'' or ''<code>b2</code>'' or both are true,
otherwise false
|<code>5 > 0 OR 5 > 10</code>
|<code>→</code> <code>True</code>
|-
|<code>NOT ''b''</code>
|true if ''<code>b</code>'' is false,
otherwise false
|<code>NOT (5 > 0)</code>
|<code>→</code> <code>False</code>
|}

=== Scoping operator (::) ===

It is possible that a model created in a previous release might contain a variable or function with the same identifier as a new built-in variable or function. In this situation, an identifier name appearing in an expression might be ambiguous.

Prepending <code>::</code> to the name of a built-in function causes the reference to always refer to the built-in function. Otherwise, the identifier refers to the user’s variable or function. With this convention, existing models are not changed by the introduction of new built-in functions.

'''Example''': Suppose a model from an older release of Analytica contains the user-defined function <code>Irr(Values, I)</code>. Then:
:<code>Irr(Payments, Time)</code> User’s <code>Irr</code> function
::<code>::Irr(Payments, Time)</code> The built-in function

===Operator binding precedence===

Analytica uses a standard precedence hierarchy resolves potential ambiguity when evaluating operators in expressions with multiple operators. For example,
:<code>1/2*3 - 3^2 + 4</code>
is interpreted as:
:<code>(((1/2)*3) - (3^2)) + 4</code>

It binds arithmetic operators before comparison operators and comparison operators before logical operators, and all of these before IF...THEN...ELSE ... and other language constructs, so:
<code>IF d + e < f^g OR a AND b > c THEN x ELSE y + z</code>
is interpreted as:
:<code>IF (((d + e) < (f^g)) OR (a AND (b > c))) THEN x ELSE (y + z)</code>

The binding precedence for operators, from most tightly bound to least tightly bound, is:

# parentheses ()
# [[Function_calls_and_parameters|function calls]]
# [[Namespaces|::]] (namespace operator)
# [[Index_Position_Operator%3A%3A@|@I]], [[Using_References#Reference_Operator:_.5CA|\A]], [[Using_References#.5C.5BI.2C_J.5DA|\[I]A]], [[Using_References#Dereference_Operator:_.23R|#R]].
# [[Index..Do#Dot_Operator:_A.I|A.I]]
# [[COM_Integration#The_Invoke_Method_operator|obj->member]] ([[COM Integration]])
# [[Not]]
# [[Subscript-Slice_Operator|A[I = x]]]
# [[Attrib of Obj]]
# [[Exponentiation_of_negative_numbers|^]]
# - (unary, negative)
# <nowiki>*, </nowiki>/
# +, - (binary, minus)
# [[Sequence_Operator|m..n]]
# [[Comparison_Operators|<, >, <=, >=, =, <>]]
# [[And]]
# [[Or]]
# [[Text_Concatenation_Operator%3A_%26|&]] (text concatenation)
# [[Assignment_Operator_%3A%3D|:=]]
# [[If-Then-Else]], [[Ifonly-Then-Else]], [[Ifall-Then-Else]]
# Sequence of statements separated by semicolons, sequence of elements or parameters separated by commas

Within each level of this hierarchy, the operators bind from left to right (left associative). For example,
:<code>1/2*3</code>
is interpreted as:
:<code>(1/2)*3</code>
not as
:<code>1/(2*3)</code>

==See Also==
* [[Comparison Operators]]
* [[Logical Operators]]
* [[Math functions]]
* [[Text functions]]
* [[Boolean or truth values]]

<footer>Text values / {{PAGENAME}} / IF a THEN b ELSE c</footer>

Date functions

2025-04-12T12:40:25Z

Fredbrunt: Reverted edits by Fredbrunt (talk) to last revision by Lchrisman

[[Category:Analytica User Guide]]
[[Category:Date and Time Functions]]
<breadcrumbs>Analytica User Guide > Text, Date, Math, and Financial Functions > {{PAGENAME}}</breadcrumbs>

__TOC__

These functions work with [[Date_and_Time_Values|date and time numbers]] — that is, the integer portion is number of days since the ''date origin'', usually Jan 1, 1904, and the fractional portion is the fraction of a day elapsed since midnight. See [[Date formats|Date numbers and the date origin]]. A date number displays as a date if you select a date format using the '''Number format''' dialog from the '''Result''' menu.

[[MakeDate]]() generates a date number from the year, month, and day. [[DatePart]]() extracts the year, month, day, or other information from a date number. [[DateAdd]]() adds a number of days, weeks, months, or years to a date. [[Today]]() returns today’s date. {{Assista||Built-in functions that work with dates and times include: Ceil, DateAdd, DatePart, Floor, IsDateTime, MakeDate, MakeTime, ParseDate, Round, Sequence, Sleep, Today and YearFrac}}{{Assista|key|List of functions that operate on date and time numbers}}

==MakeDate(year, month, day)==
Gives the date value for the date with given «year», «month», and «day». If omitted, «month» and «day» default to 1. Parameters must be positive integers.

See also [[MakeDate]]().

'''Examples:'''

:<code>MakeDate(2007, 5, 15) → 15-May-2007</code>
:<code> MakeDate(2000) → 1-Jan-2000</code>

'''Library:''' [[Special_Functions_library|Special Functions]]

==MakeTime(h, m, s)==
Gives the fraction of a day elapsed since midnight for the given hour, minute and second. The hour, «h», is typically between 0 and 23 inclusive (but can be greater than 23 when encoding a duration of more than one day). Minutes «m» and seconds «s» must be between 0 and 59 inclusive.

See also [[MakeTime]]().

'''Examples:'''

:<code>MakeTime(12, 0, 0) → 0.5</code>
:<code>MakeTime(15, 30, 0) → 0.6458 {3:30:00 pm}</code>

'''Library:''' Special Functions

==DatePart(date, part)==
Given a date-time value «date», [[DatePart]]() returns the year, month, day, hour, minute, or seconds as a number, according to the value of «part», which must be an uppercase character:

* <code>Y</code> gives the four digit year as a number, such as 2006.
* <code>Q</code> gives the quarter as a number between 1 and 4.
* <code>M</code> gives the month as a number between 1 and 12.
* <code>D</code> gives the day as number between 1 and 31.
* <code>W</code> gives the day of the week as a number from 1 (Sunday) to 7 (Saturday).
* <code>H</code> gives the hour on a 24-hour clock (0 to 23).
* <code>h</code> gives the hour on a 12-hour close (1 to 12).
* <code>m</code> gives the minutes (0 to 59).
* <code>s</code> gives the seconds (0 to 59.99).

Other date options for «part» are: <code>YY → '06', MM →'01', MMM → 'Jan', MMMM → 'January', DD → '09', ddd → '1st', dddd → 'first', Dddd → 'First', www → 'Mon', wwww → 'Monday'</code>, and <code>q → 1 to 4</code> for number of quarter of the year.

Other time options for «part» are: <code>HH → '15', hh → '03', mm →'05'</code>, and <code>ss →'00'</code>.

[[DatePart]]() can also weeks or weekdays elapsed since the date origin or in the current year.

* <code>wd</code> (or <code>wd+</code>) gives the number of weekdays since the date origin including the indicated day.
* <code>wd-</code> gives the number of weekdays since the date origin not including the indicated day.
* <code>#d</code> gives the day number in the current year
* <code>#w</code> gives the week number in the current year (the week starting on Sunday)
* <code>#wm</code> gives the week number in the current year (the week starting on Monday)

The <code>#w</code> and <code>#wm</code> options consider the week containing Jan 1 to be week 1. Options <code>e#w</code> and <code>e#wm</code> return the European standard in which <code>week1</code> is the first week containing at least 3 days.

'''Examples:'''

:<code>DatePart(MakeDate(2006, 2, 28), 'D') → 28</code>

This makes a sequence of all weekdays between <code>Date1</code> and <code>Date2</code>:

:<code>Index J := Date1 .. Date2;</code>
:<code>Subset(DatePart(J, "W") >= 2 AND DatePart(J, "W") <= 6)</code>

This computes the number of weekdays between two dates, including both endpoints:

:<code>DatePart(date2, 'wd+') - DatePart(date1, 'wd-')</code>

'''Library:''' Special Functions

==DateAdd(date, n, unit)==
Given a date value «date», it returns a date value offset by «n» years, months, days, weekdays, hours, minutes or seconds, according to whether «unit» is <code>Y, Q, M, D, WD, h, m</code>, or <code>s</code>. If «n» is negative, it subtracts units from the date.

'''Examples:'''

[[DateAdd]]() is especially useful for generating a sequence of dates, e.g., weeks, months, or quarters, for a time index:

:<code>DateAdd(MakeDate(2006, 1, 1), 0 .. 12, "M") → ["1 Jan 2006", "1 Feb 2006", "1 Mar 2006", ... "1 Jan 2007"]</code>

If an offset would appear to go past the end of a month, it returns the last day of the month:

:<code>DateAdd(MakeDate(2004, 2, 29), 1, 'Y' ) → 2005-Feb-28</code>
:<code>DateAdd(MakeDate(2006, 10, 31), 1, 'M' ) → 2006-Nov-30</code>

Since the dates <code>2005-Feb-29</code> and <code>2006-Nov-31</code> don’t exist, it gives the last day of the preceding month.

Adding a day offset, <code>DateAdd(date, n, "D")</code>, is equivalent to <code>date + n</code>. <code>DateAdd(date, n, "WD")</code> adds the specified number of weekdays to the first weekday equal to or falling after <code>date</code>.

'''Library:''' Special Functions

==Today(''withTime, utc'')==
Returns the current date (or optionally date and time) as a date number — the number of days since the date origin, usually Jan 1, 1904. Unlike other functions, it gives a different value depending on what day (and time) it is evaluated. It is most often called with no parameters, [[Today]](), in which case the result is an integer representing the date in your local time zone. Including the optional parameter «withTime», <code>Today(withTime: True)</code> returns the current time of day in the fractional part. <code>Today(withTime: true, utc: True)</code> with the optional «utc» parameter, turns the coordinated universal date-time rather than the local date-time.

Since variables usually cache (retain) their value after computing it, the date could become out of date if the Analytica session extends over midnight. But, it will be correct again when you restart the model.

'''Library:''' Special Functions

==ParseDate(date, ''badVal'')==
[[ParseDate]]() parses a textual date or time into a numeric value representing the number of days elapsed since the date origin. The parsing occurs independent of the number format setting for the variable being evaluated. The second optional parameter, «badVal», specifies the return value when «date» is not textual or cannot be parsed as a date. When omitted, «badVal» defaults to [[Null]].

:<code>ParseDate("July 22, 2009") → 2009-Jul-22 {38554}</code>
:<code>ParseDate("38554") → «null»</code>
:<code>ParseDate("3:00 pm") → 0.625</code>
:<code>ParseDate("7/22/2009 15:00:00") → 2009-Jul-22 3:00pm {38554.625}</code>
:<code>Var x := ["hello", "7-22-2009"] Do ParseDate(x, x) → ["hello", 38554]</code>

'''''Note:''' The results in this example assume the default date origin of 1-Jan-1904 and that Windows is set to United States regional settings.''

==Sequence(start, end, dateUnit, step)==
The [[Functions_that_create_indexes#m_.._n|Sequence function]] can be used to create a sequence of dates or date-times. A date or time sequence is created when «start» and «end» are date-time numbers, or when the «dateUnit» parameter is specified. The «dateUnit» parameter can be any of <code>"Y", "Q", "M", "D", "WD", "h", "m"</code>, or <code>"s"</code>. Note that options <code>"Y", "Q", "M"</code>, and <code>"WD"</code> result in increments that have date-aware spacings, but in which the increment measured in days actually varies, due to variations in the lengths of months, the positions of weekends, and the presence of leap years.

:<code>Sequence(9-Aug-2012, 15-Aug-2012, dateUnit: "WD") → [9-Aug-2012, 10-Aug-2012, 13-Aug-2012, 14-Aug-2012, 15-Aug-2012]</code>
:<code>Sequence(1-Jan-2012, 1-Jan-2013, dateUnit: "Q") → [1-Jan-2012, 1-Apr-2012, 1-Jul-2012, 1-Oct-2012, 1-Jan-2013]</code>
:<code>Sequence(1-Jan-2012, 1-May-2012, dateUnit: "M") → [1-Jan-2012, 1-Feb-2012, 1-Mar-2012, 1-Apr-2012, 1-May-2013]</code>

The «step» parameter can also be specified, for example, to step in increments of 2 months. When specified with a «dateUnit» increment, «step» must be an integer value. If it is not an integer, it is rounded down.

See also [[Sequence]]().

==Ceil(x, dateUnit:...), Floor(x, dateUnit:...), Round(x, dateUnit:...)==
These rounding functions (described in [[Math functions]]) can be used to round dates or times to the nearest date unit (i.e., nearest year, month, day, weekday, hour, minute or second) by specifying the optional «dateUnit» parameter. The date unit can be one of the following values: <code>"Y", "Q", "M", "D", "WD", "h", "m"</code>, or <code>"s"</code>. To specify «dateUnit», you should use a named-parameter syntax.

:<code>Ceil(11-Aug-2012, dateUnit: ["Y", "Q", "WD", "Q"]) → [1-Jan-2013, 1-Oct-2012, 1-Sep-2012, 13-Aug-2012]</code>
:<code>Floor(11-Aug-2012, dateUnit: ["Y", "Q", "WD", "Q"]) → [1-Jan-2012, 1-Jul-2012, 1-Aug-2012, 10-Aug-2012]</code>
:<code>Round(11-Aug-2012, dateUnit: ["Y", "Q", "WD", "Q"]) → [1-Jan-2013, 1-Jul-2012, 1-Aug-2012, 10-Aug-2012]</code>

See more at [[Ceil]](), [[Floor]]() and [[Round]]().

== Sleep( ''seconds, untilTime'' ) ==
(''New in [[Analytica 5.0]]'') Pauses the computation either for «seconds» seconds, or until the date-time «untilTime» is reached, or both. Also forces pending redraw events to be processed when the function is called. See [[Sleep]] for details and examples.

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Date Functions]]
* [[Date formats]]
* [[Date and Time Values]]
* [[Special Handling of Date Values]]
* [[MakeDate]]()
* [[MakeTime]]()
* [[DatePart]]()
* [[DateAdd]]()
* [[Today]]()
* [[ParseDate]]()
* [[Sequence]]()
* [[Ceil]]()
* [[Floor]]()
* [[Round]]()
* [[Sleep]]()
</div>

<footer>Text functions / {{PAGENAME}} / Advanced math functions</footer>

Date functions

2025-04-12T12:35:49Z

Fredbrunt: /* Sequence(start, end, dateUnit, step) */ fixed sequence example

[[Category:Analytica User Guide]]
[[Category:Date and Time Functions]]
<breadcrumbs>Analytica User Guide > Text, Date, Math, and Financial Functions > {{PAGENAME}}</breadcrumbs>

__TOC__

These functions work with [[Date_and_Time_Values|date and time numbers]] — that is, the integer portion is number of days since the ''date origin'', usually Jan 1, 1904, and the fractional portion is the fraction of a day elapsed since midnight. See [[Date formats|Date numbers and the date origin]]. A date number displays as a date if you select a date format using the '''Number format''' dialog from the '''Result''' menu.

[[MakeDate]]() generates a date number from the year, month, and day. [[DatePart]]() extracts the year, month, day, or other information from a date number. [[DateAdd]]() adds a number of days, weeks, months, or years to a date. [[Today]]() returns today’s date. {{Assista||Built-in functions that work with dates and times include: Ceil, DateAdd, DatePart, Floor, IsDateTime, MakeDate, MakeTime, ParseDate, Round, Sequence, Sleep, Today and YearFrac}}{{Assista|key|List of functions that operate on date and time numbers}}

==MakeDate(year, month, day)==
Gives the date value for the date with given «year», «month», and «day». If omitted, «month» and «day» default to 1. Parameters must be positive integers.

See also [[MakeDate]]().

'''Examples:'''

:<code>MakeDate(2007, 5, 15) → 15-May-2007</code>
:<code> MakeDate(2000) → 1-Jan-2000</code>

'''Library:''' [[Special_Functions_library|Special Functions]]

==MakeTime(h, m, s)==
Gives the fraction of a day elapsed since midnight for the given hour, minute and second. The hour, «h», is typically between 0 and 23 inclusive (but can be greater than 23 when encoding a duration of more than one day). Minutes «m» and seconds «s» must be between 0 and 59 inclusive.

See also [[MakeTime]]().

'''Examples:'''

:<code>MakeTime(12, 0, 0) → 0.5</code>
:<code>MakeTime(15, 30, 0) → 0.6458 {3:30:00 pm}</code>

'''Library:''' Special Functions

==DatePart(date, part)==
Given a date-time value «date», [[DatePart]]() returns the year, month, day, hour, minute, or seconds as a number, according to the value of «part», which must be an uppercase character:

* <code>Y</code> gives the four digit year as a number, such as 2006.
* <code>Q</code> gives the quarter as a number between 1 and 4.
* <code>M</code> gives the month as a number between 1 and 12.
* <code>D</code> gives the day as number between 1 and 31.
* <code>W</code> gives the day of the week as a number from 1 (Sunday) to 7 (Saturday).
* <code>H</code> gives the hour on a 24-hour clock (0 to 23).
* <code>h</code> gives the hour on a 12-hour close (1 to 12).
* <code>m</code> gives the minutes (0 to 59).
* <code>s</code> gives the seconds (0 to 59.99).

Other date options for «part» are: <code>YY → '06', MM →'01', MMM → 'Jan', MMMM → 'January', DD → '09', ddd → '1st', dddd → 'first', Dddd → 'First', www → 'Mon', wwww → 'Monday'</code>, and <code>q → 1 to 4</code> for number of quarter of the year.

Other time options for «part» are: <code>HH → '15', hh → '03', mm →'05'</code>, and <code>ss →'00'</code>.

[[DatePart]]() can also weeks or weekdays elapsed since the date origin or in the current year.

* <code>wd</code> (or <code>wd+</code>) gives the number of weekdays since the date origin including the indicated day.
* <code>wd-</code> gives the number of weekdays since the date origin not including the indicated day.
* <code>#d</code> gives the day number in the current year
* <code>#w</code> gives the week number in the current year (the week starting on Sunday)
* <code>#wm</code> gives the week number in the current year (the week starting on Monday)

The <code>#w</code> and <code>#wm</code> options consider the week containing Jan 1 to be week 1. Options <code>e#w</code> and <code>e#wm</code> return the European standard in which <code>week1</code> is the first week containing at least 3 days.

'''Examples:'''

:<code>DatePart(MakeDate(2006, 2, 28), 'D') → 28</code>

This makes a sequence of all weekdays between <code>Date1</code> and <code>Date2</code>:

:<code>Index J := Date1 .. Date2;</code>
:<code>Subset(DatePart(J, "W") >= 2 AND DatePart(J, "W") <= 6)</code>

This computes the number of weekdays between two dates, including both endpoints:

:<code>DatePart(date2, 'wd+') - DatePart(date1, 'wd-')</code>

'''Library:''' Special Functions

==DateAdd(date, n, unit)==
Given a date value «date», it returns a date value offset by «n» years, months, days, weekdays, hours, minutes or seconds, according to whether «unit» is <code>Y, Q, M, D, WD, h, m</code>, or <code>s</code>. If «n» is negative, it subtracts units from the date.

'''Examples:'''

[[DateAdd]]() is especially useful for generating a sequence of dates, e.g., weeks, months, or quarters, for a time index:

:<code>DateAdd(MakeDate(2006, 1, 1), 0 .. 12, "M") → ["1 Jan 2006", "1 Feb 2006", "1 Mar 2006", ... "1 Jan 2007"]</code>

If an offset would appear to go past the end of a month, it returns the last day of the month:

:<code>DateAdd(MakeDate(2004, 2, 29), 1, 'Y' ) → 2005-Feb-28</code>
:<code>DateAdd(MakeDate(2006, 10, 31), 1, 'M' ) → 2006-Nov-30</code>

Since the dates <code>2005-Feb-29</code> and <code>2006-Nov-31</code> don’t exist, it gives the last day of the preceding month.

Adding a day offset, <code>DateAdd(date, n, "D")</code>, is equivalent to <code>date + n</code>. <code>DateAdd(date, n, "WD")</code> adds the specified number of weekdays to the first weekday equal to or falling after <code>date</code>.

'''Library:''' Special Functions

==Today(''withTime, utc'')==
Returns the current date (or optionally date and time) as a date number — the number of days since the date origin, usually Jan 1, 1904. Unlike other functions, it gives a different value depending on what day (and time) it is evaluated. It is most often called with no parameters, [[Today]](), in which case the result is an integer representing the date in your local time zone. Including the optional parameter «withTime», <code>Today(withTime: True)</code> returns the current time of day in the fractional part. <code>Today(withTime: true, utc: True)</code> with the optional «utc» parameter, turns the coordinated universal date-time rather than the local date-time.

Since variables usually cache (retain) their value after computing it, the date could become out of date if the Analytica session extends over midnight. But, it will be correct again when you restart the model.

'''Library:''' Special Functions

==ParseDate(date, ''badVal'')==
[[ParseDate]]() parses a textual date or time into a numeric value representing the number of days elapsed since the date origin. The parsing occurs independent of the number format setting for the variable being evaluated. The second optional parameter, «badVal», specifies the return value when «date» is not textual or cannot be parsed as a date. When omitted, «badVal» defaults to [[Null]].

:<code>ParseDate("July 22, 2009") → 2009-Jul-22 {38554}</code>
:<code>ParseDate("38554") → «null»</code>
:<code>ParseDate("3:00 pm") → 0.625</code>
:<code>ParseDate("7/22/2009 15:00:00") → 2009-Jul-22 3:00pm {38554.625}</code>
:<code>Var x := ["hello", "7-22-2009"] Do ParseDate(x, x) → ["hello", 38554]</code>

'''''Note:''' The results in this example assume the default date origin of 1-Jan-1904 and that Windows is set to United States regional settings.''

==Sequence(start, end, dateUnit, step)==
The [[Functions_that_create_indexes#m_.._n|Sequence function]] can be used to create a sequence of dates or date-times. A date or time sequence is created when «start» and «end» are date-time numbers, or when the «dateUnit» parameter is specified. The «dateUnit» parameter can be any of <code>"Y", "Q", "M", "D", "WD", "h", "m"</code>, or <code>"s"</code>. Note that options <code>"Y", "Q", "M"</code>, and <code>"WD"</code> result in increments that have date-aware spacings, but in which the increment measured in days actually varies, due to variations in the lengths of months, the positions of weekends, and the presence of leap years.

:<code>Sequence(9-Aug-2012, 15-Aug-2012, dateUnit: "WD") → [9-Aug-2012, 10-Aug-2012, 11-Aug-2012, 12-Aug-2012, 13-Aug-2012, 14-Aug-2012, 15-Aug-2012]</code>
:<code>Sequence(1-Jan-2012, 1-Jan-2013, dateUnit: "Q") → [1-Jan-2012, 1-Apr-2012, 1-Jul-2012, 1-Oct-2012, 1-Jan-2013]</code>
:<code>Sequence(1-Jan-2012, 1-May-2012, dateUnit: "M") → [1-Jan-2012, 1-Feb-2012, 1-Mar-2012, 1-Apr-2012, 1-May-2013]</code>

The «step» parameter can also be specified, for example, to step in increments of 2 months. When specified with a «dateUnit» increment, «step» must be an integer value. If it is not an integer, it is rounded down.

See also [[Sequence]]().

==Ceil(x, dateUnit:...), Floor(x, dateUnit:...), Round(x, dateUnit:...)==
These rounding functions (described in [[Math functions]]) can be used to round dates or times to the nearest date unit (i.e., nearest year, month, day, weekday, hour, minute or second) by specifying the optional «dateUnit» parameter. The date unit can be one of the following values: <code>"Y", "Q", "M", "D", "WD", "h", "m"</code>, or <code>"s"</code>. To specify «dateUnit», you should use a named-parameter syntax.

:<code>Ceil(11-Aug-2012, dateUnit: ["Y", "Q", "WD", "Q"]) → [1-Jan-2013, 1-Oct-2012, 1-Sep-2012, 13-Aug-2012]</code>
:<code>Floor(11-Aug-2012, dateUnit: ["Y", "Q", "WD", "Q"]) → [1-Jan-2012, 1-Jul-2012, 1-Aug-2012, 10-Aug-2012]</code>
:<code>Round(11-Aug-2012, dateUnit: ["Y", "Q", "WD", "Q"]) → [1-Jan-2013, 1-Jul-2012, 1-Aug-2012, 10-Aug-2012]</code>

See more at [[Ceil]](), [[Floor]]() and [[Round]]().

== Sleep( ''seconds, untilTime'' ) ==
(''New in [[Analytica 5.0]]'') Pauses the computation either for «seconds» seconds, or until the date-time «untilTime» is reached, or both. Also forces pending redraw events to be processed when the function is called. See [[Sleep]] for details and examples.

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Date Functions]]
* [[Date formats]]
* [[Date and Time Values]]
* [[Special Handling of Date Values]]
* [[MakeDate]]()
* [[MakeTime]]()
* [[DatePart]]()
* [[DateAdd]]()
* [[Today]]()
* [[ParseDate]]()
* [[Sequence]]()
* [[Ceil]]()
* [[Floor]]()
* [[Round]]()
* [[Sleep]]()
</div>

<footer>Text functions / {{PAGENAME}} / Advanced math functions</footer>

Text functions

2025-04-12T02:45:25Z

Fredbrunt: /* NumberToText(x, format) */ Removed space from within number so it match DTA result

[[Category:Analytica User Guide]]
[[Category: Text Functions]]
<breadcrumbs>Analytica User Guide > Text, Date, Math, and Financial Functions > {{PAGENAME}}</breadcrumbs>

These functions work with [[text values]] (sometimes known as strings), available in the built-in Text library.

__TOC__

==Asc(t)==

Returns the numeric character code of the first character in text value «t». This is occasionally useful, for example to understand the alphabetic ordering of text values. Unicode characters may have values greater that 255.

:Asc('d') → 100
:Asc('δ') → 948 { or, in hex, 0x3b4 }

See also [[Asc]](t).

==Chr(n)==
Returns the character corresponding to the numeric unicode code «n». [[Chr]]() and [[Asc]]() are inverses of each other, for example:

:<code>Chr(65) → 'A', Asc(Chr(65)) → 65</code>
:<code>Asc('A') → 65, Chr(Asc('A')) → 'A'</code>

[[Chr]]() is useful for creating characters that cannot easily be typed, such as ''Tab'', which is <code>Chr(9)</code> and ''carriage return (CR)'', which is <code>Chr(13)</code>. For example, if you read in a text file, <code>x</code>, you can use
<code>[[SplitText]](x, Chr(13))</code> to generate an array of lines from a multiline text file.

==TextLength(t)==
Returns the number of characters in text «t».

See also [[TextLength]]().

:<code>TextLength('supercalifragilisticexpialidocious') → 34</code>

==SelectText(t, m, n)==
Returns text containing the «m»'th through the «n»'th character of text «t» (where the first character is «m»=1). If you omit «n» it returns characters from the «m»'th through the end of «t».

See also [[SelectText]]().

:<code>SelectText('One or two', 1, 3) → 'One'</code>
:<code>SelectText('One or two', 8) → 'two'</code>

==FindInText(substr, text, ''start, caseInsensitive, re, return, subpattern, repeat, repeatSubpattern, repeatIndex'')==
Returns the position of the first occurrence of «substr» within «text», as the number of characters to the first character of text. If it can't find «substr» in text, it returns 0.

:<code>Variable People := 'Amy, Betty, Carla'</code>
:<code>FindInText('Amy', People) → 1</code>
:<code>FindInText('Betty', People) → 6</code>
:<code>FindInText('Fred', People) → 0</code>

=== Optional parameters ===

==== CaseInsensitive ====
[[FindInText]]() is case-sensitive unless the optional parameter «caseInsensitive» is true:
:<code>FindInText('amy', People) → 0</code>
:<code>FindInText('amy', People, caseInsensitive: true) → 1</code>

==== Start ====
The optional third parameter, «start», specifies the position to start searching at, for example, if you want to find a second occurrence of «substr» after you have found the first one.

:<code>FindInText('i','Supercalifragilisticexpialidocious') → 9</code>
:<code>FindInText('i','Supercalifragilisticexpialidocious', 10) → 14</code>

==== Repeat, RepeatIndex ====
Normally [[FindInText]]() returns information on the first match, but by using any of the three optional repeat parameters can be used to find all matches in text. When it finds multiple matches, the result is an array. If you specify<code>repeat: true</code>, the resulthas a local index named <code>.Repeat</code> with elements <code>1..n</code>.

Alternatively, you can specify a preexisting index as «repeatIndex» parameter. If that index has ''n'' elements, it returns only the first ''n'' matches.

This example parses XML text, returning an array of ages with a local index named «.Name», where the labels of the local index are the names of each person:

:<code>FindInText('<person.*?name = "(?<name>(.*?))".*?>.*?' & '<age>(?<age>.*?)</age>.*?' & '</person>', xmlText, re: true, return: 'S', repeatSubpattern: 'name', subpattern: 'age')</code>

==== Re (Regular expression), Return, and Subpattern ====

If you set optional parameter, «re», to <code>True,</code>it interprets «substr» as a ''regular expression''. The regular expression language is widely used (not just in Analytica) to specify match criteria for text. It offers "wild cards" that match any letter, digit, or other character, identify separate words, and a lot more. See [[Regular expression]]s for details.

Parentheses within a regular expression denote subpatterns, numbered in a depth first fashion. Subpatterns can also be named using the regular expression format “<code>(?<name>...)</code>”. You can the match information for any subpattern by specifying the subpattern number or subpattern name in the optional «subpattern» parameter.

:<code>FindInText('d.*T', 'FindInText', re:1) → 4</code>
:<code>FindInText('d.*T', 'FindInText', re: 1, return:['L', 'S']) → [4, 'dInT']</code>
:<code>FindInText('(\d\d\d)-(\d\d\d\d)', '650-212-1212', re:1, return:'S', subpattern:[0, 1, 2]) → ['212-1212', ’212’, ’1212’]</code>
:<code>FindInText('a*(?<bcd>b+(c+)(d*))','zyabdaabbcccfd', re:1, subpattern:['bcd', 0, 1, 2, 3]) → [8, 6, 8, 10, 13]</code>

The «return» parameter alters what is returned, according to what letter you provide as the parameter:

* ‘P’ (or ‘Position’): The position of the matching text or subpattern (default)
* ‘L’ (or ‘Length’): The length of the matching text or subpattern.
* 'S’ (or ‘Subpattern’): The text matched the regular expression or subpattern.
* ‘#’ (or ‘#Subpatterns’): The number of subpatterns in the regular expression.

==TextTrim(t, ''leftOnly, rightOnly, trimChars'')==
Removes leading and trailing spaces from the text «t».
:<code>TextTrim(' Hello World ') → 'Hello World'</code>

Set optional parameter «leftOnly» to True to remove only preceding spaces, or set «rightOnly» to True to remove only followingspaces:
:<code>TextTrim(' Hello World ', leftOnly: True) → 'Hello World'</code>
:<code>TextTrim(' Hello World ', rightOnly: True) → ' Hello World'</code>

To remove characters other than spaces, specify those characters in a text for the optional «trimChars» parameter:
:<code>TextTrim(' [One, Two, Three] ', trimChars: ' []') → 'One, Two, Three'</code>

==TextReplace(text, pattern, substr, ''all, caseInsensitive, re'')==
Returns text with the first occurrence of «pattern» replaced by «substr».

<code>TextReplace('StringReplace, StringLength', 'String', 'Text') → 'TextReplace, StringLength'</code>

If «all» is <code>True</code>, it returns «text» with ''all'' occurrences of text «pattern» replaced by «subst».
:<code>TextReplace('StringReplace, StringLength', 'String', 'Text', All: True) → 'TextReplace, TextLength'</code>
Matches are case-sensitive unless «caseInsensitive» is <code>True</code>.

==== Re (Regular expression) ====
When the optional «re» parameter is <code>True</code>, it treats «pattern» as a [[regular expression]]. In this mode, it replaces the character sequence <code>\0</code> in «subst» by the matching text, and it replaces <code>\1, \2, ..., \9</code> by the subtext matched by the corresponding numbered subpattern in the regular expression. The character sequence <code>''<name>''</code> in «subst» is replaced by the subtext matched to the indicated named subpattern.

:<code>TextReplace('Hello world', '\w+', '«\0»', all:True, re: True) → '«Hello» «world»'</code>
:<code>TextReplace('Hello world', '(.{1, 7}).*', '\1…', re: True) → 'Hello w…'</code>
:<code>TextReplace(text: 'swap first and last', pattern: '(?<first>\w+)(?<mid>.*)(?<last>\b\w+)', subst:'<last><mid><first>', re: True) → 'last first and swap’</code>
:<code>TextReplace('swap first and last', '(\w)(\w*)(\w)', '\3\2\1', re: 1, all: 1 ) → 'pwas tirsf dna tasl'</code>

==Joining Text: a & b==
The [[Text_Concatenation_Operator%3A_%26|&]] operator joins (concatenates) two text values to form a single text value, for example:

:<code>'What is the' & ' number' & '?' → 'What is the number?'</code>

If one or both operands are numbers, it converts them to text using the number format of the variable whose definition contains this function call (or the default suffix format if none is set), for example:

:<code>'The number is ' & 10^8 → 'The number is 100M'</code>

This is also useful for converting (or “coercing”) numbers to text. The [[NumberToText]] function is also useful for converting numbers to text when you want to specify the number format explicitly.

The result of concatenation of text with the special value [[Null]] changed in the [[Analytica 5.0]] release:
:<code>'The value is ' & Null → 'The value is Null'</code>     ''{in [[Analytica 5.0]] and later}''
:<code>'The value is ' & Null → «null»</code>     ''{in [[Analytica 4.6]] and earlier}''

==JoinText(a, i, ''separator, finalSeparator, default, textForNull'')==
Returns the elements of array «a» joined together into a single text value over index «i». If elements of «a» are numeric, [[JoinText]]() first converts them to text using the number format settings for the variable whose definition contains this function call. For example:

:<code>I := ['A', 'B', 'C']</code>
:<code>JoinText(I, I) → 'ABC'</code>
:<code>A := Array(I, ['VW', 'Honda', 'BMW'])</code>
:<code>B := Array(I, ['one', Null, 'two'])</code>
:<code>JoinText(A, I) → 'VWHondaBMW'</code>

If the optional parameter «separator» is specified, it is inserted as a separator between successive elements, for example:

:<code>JoinText(A, I, ', ') → 'VW, Honda, BMW'</code>

The optional parameter «finalSeparator», if present, specifies a different separator between the second-to-last and last elements of «a».

:<code>JoinText(A, I, '; ', '; and ') → 'VW; Honda; and BMW'</code>

Null values in «a» are ignored unless the optional parameter «textForNull» is specified.

:<code>JoinText(B, I, ', ') → 'one, two'</code>
:<code>JoinText(B, I, ', ', textForNull: '') → 'one, , two'</code>
:<code>JoinText(B, I, ', ' , textForNull: 'NULL') → 'one, NULL, two'</code>

The optional «default» parameter is returned when all values are ignored, or «a» has a zero length.

:<code>JoinText([Null, Null, Null], default: Null) → «null»</code>

==SplitText(text, separator, ''caseInsensitive, re'')==
Returns a list of text values formed by splitting the elements of text value text at each occurrence of separator «separator». For example:

:<code>SplitText('VW, Honda, BMW', ', ') → ['VW', 'Honda', 'BMW']</code>

[[SplitText]]() is the inverse of [[JoinText]](), if you use the same separators. For example:

:<code>Var x := SplitText('Humpty Dumpty sat on a wall.', ' ') → ['Humpty', 'Dumpty', 'sat', 'on', 'a', 'wall.']</code>
:<code>JoinText(x, , ' ') → 'Humpty Dumpty sat on a wall.'</code>

When «separator» contains letters, setting «caseInsensitive» to <code>True</code> matches in a lower/uppercase-insensitive manner. When the «re» parameter is <code>True</code>, separator is interpreted as a Perl-compatible [[regular expression]].

:<code>Variable s := 'Yes, Virginia. There is a Santa Claus!'</code>
:<code>SplitText(s, '[\s, \.!]+', re: 1) → ['Yes', 'Virginia', 'There', 'is', 'a', 'Santa', 'Claus', '']</code>
:<code>SplitText(TextTrim(s, trimChars: ' , .!'), '[\s, \.!]+', re:1) → ['Yes', 'Virginia', 'There', 'is', 'a', 'Santa', 'Claus']</code>

<tip title="Tip> With [[SplitText]](), «text» must be a single text value, not an array. Otherwise, it might generate an array of arrays of different length. See [[Ensuring Array Abstraction|Functions expecting atomic parameters]] on what to do if you want apply it to an array.
</Tip>

==TextLowerCase(t)==
[[TextLowerCase]]() returns the text «t» with all letters as lowercase. For example:

:<code>TextLowerCase('What does XML mean?') → 'what does xml mean?'</code>

==TextUpperCase(t)==
[[TextUpperCase]]() returns the text «t» with all letters as uppercase. For example:

:<code>TextUpperCase('What does XML mean?') → 'WHAT DOES XML MEAN?'</code>

==TextSentenceCase(Text, ''preserveUC'')==
[[TextSentenceCase]]() returns the text «t» with the first character (if a letter) as uppercase, and any other letters as lowercase. For example:

:<code>TextSentenceCase('mary ann FRED Maylene') → 'Mary ann fred maylene'</code>
:<code>TextSentenceCase(SplitText('mary ann FRED Maylene', ' ')) → ['Mary', 'Ann', 'Fred', 'Maylene']</code>
:<code>TextSentenceCase('they are Fred and Maylene', true) → 'They are Fred and Maylene'</code>

==NumberToText(x, format)==

NumberToText() converts number «x» to text using the specified «format». It provides all the settings and options available in the [[Number formats]] dialog for displaying a number (including a date number).

Possible values for «format» are: <code>'Suffix', 'Exponential', 'Fixed Point', 'Integer', 'Percent', 'Date', 'Boolean'</code>, or <code>'Hexadecimal'</code>. You can just use the first letter of a format to keep it brief:

:<code>NumberToText(3.45M, ['S', 'E', 'F', 'I', 'H']) → ['3.45M', '3.45.e+006', '3450000', '3450000', '0x34a490']</code>
:<code>NumberToText(0.0012, ['S', 'E', 'F', 'P']) → ['1.2m', '1.2e-003', '0', 0.12%']</code>

NumberToText() offers these optional parameters:

*«digits» specifies the precision for Suffix and Exponential formats, and the digits to the right of the decimal for Fixed Point and Percent formats, for example:

:<code>NumberToText(Pi, 'Suffix', digits: 5) → '3.1416'</code>
:<code>NumberToText(Pi, 'Fixed Point', digits: 5) → '3.14159'</code>
:<code>NumberToText(Pi, 'Percent', digits: 5) → '314.15927%'</code>

* «showZeros» forces the inclusion of trailing zeros:

:<code>NumberToText(1/4, 'Percent', digits: 2, showZeros: True) → '25.00%'</code>

Set «thousandsSeparators» to <code>True</code> to separate digits into groups of three:

:<code>NumberToText(7^12,'I', thousandsSeparators: True) → '13,841,287,201'</code>

* «currency» specifies a template with the currency symbol and its placement relative to the number and the minus sign.

:<code>NumberToText(-372, 'F', currency: ['-£#', 'US$-#', '#£-', '($#)']) → ['-£372', 'US$-372', '372£-', '($372)']</code>

* «dateFormat» provides a date format template for converting [[date numbers]] to text:

:<code>NumberToText(Today(), dateFormat: 'yyyy MMMM dd (wwww)') → '2013 July 01 (Monday)'</code>

* «fullPrecision»: Set this to true, to include all digits to ensure that the full precision of the number.

:<code>NumberToText(Pi, fullPrecision: True) → '3.141592653589793'</code>

== ParseNumber(text, ''badVal'') ==

Parses a text value into a number. (For dates, use [[ParseDate]]()). The result is independent of the number format setting. Values that are already numeric are returned. If the number is unparseable, it returns <code>Null</code>, unless you specify a different value to the optional parameter «badVal».

:<code>ParseNumber('12.43K') → 12.43K</code>
:<code>ParseNumber('hello') → «null»</code>
:<code>ParseNumber(14.3) → 14.3</code>

If you use <code>ParseNumber(x, x)</code> it will simply return any unparseable text values in «x» as the original text value:

:<code>VAR x := ['3, 214', 14, 'foo'] DO ParseNumber(x, x) → [ 3214, 14, 'foo']</code>

==TextCharacterEncode(type,text)==
(''New to [[Analytica 5.0]]'' ) Transforms «text» into an alternative text encoding specified by «type». The text can be ''URL encoded'' for inclusion in a URL or ''URL decoded'', ''XML encoded'', put into one of the four normalized unicode forms, or converted to or from a UTF-8 encoding. See [[TextCharacterEncode]].
:<code>TextCharacterEncode('UTF-8', 'γσh') → 'Î³Ïh'</code>
:<code>TextCharacterDecode('-UTF-8','Î³Ïh') → 'γσh'</code>
:<code>TextCharacterEncode('URL','3:4 = 3/4 & 1/2 = 0.5') → '3%3A4+%3D+3%2F4+%26+1%2F2+%3D+0.5'</code>

== TextDistance(t1,t2) ==
(''New to [[Analytica 5.0]]'' ) Returns a distance measure indicating how different two text values are. The result is the number of edit steps (substitutions, deletions, insertions, etc.) are required to transform «t1» into «t2». Many optional parameters can be used to specify which editing operations are allowed (see [[TextDistance]]()), allowing various standard distance measures including Levenshtein distance, Demerau-Levenshtein distance, Hamming distance, and Longest common subsequence among others.

:<code>[[TextDistance]]("portland", "orlando") → 3</code>
::Note: <code>"portland" → "ortland" → "orland" → "orlando"</code>

== Data file parsing and creation functions ==
When you exchange data with other applications (which in generally requires the [[Analytica Enterprise]] edition or better), you may need to parse the data, or put your data into a given format. Commonly used formats include CSV (which stands for Comma Separated Values, but includes other separators such as tabs), XML and JSON. The following functions can be used to parse or create data in these formats:
* [[ParseCSV]] and [[MakeCSV]]
* [[ParseJSON]] and [[MakeJSON]]
* The Microsoft XML DOM parser. See [[Example_Models#Extracting_Data_from_an_XML_file|Parsing an XML file]]. This uses [[COM Integration]] and requires the [[Analytica Enterprise]] edition.

:<code>[[ParseCSV]]( [[ReadTextFile]]( "MyData.csv" ) )</code> → { 2-D array indexed by local indexes <code>.Column</code> and <code>.Row</code>}

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Regular Expressions]]
* [[Asc]]()
* [[Chr]]()
* [[TextLength]]()
* [[SelectText]]()
* [[ FindInText]]()
* [[TextTrim]]()
* [[TextReplace]]()
* [[Text Concatenation Operator: &]]
* [[JoinText]]()
* [[SplitText]]()
* [[TextLowerCase]]()
* [[TextUpperCase]]()
* [[TextSentenceCase]]()
* [[NumberToText]]()
* [[TextDistance]]()
* [[TextCharacterEncode]]()
* [[Numbers and text]]
* [[Converting Numbers to Text]]
* [[ParseNumber]]()
* [[Model File Character Encoding]]
* [[Read and write text files]]
* [[Files and Editing]]
* [[Multiple formats in one table]]

</div>

<footer>Text, Date, Math, and Financial Functions / {{PAGENAME}} / Date functions</footer>

Text functions

2025-04-10T05:06:40Z

Fredbrunt: /* JoinText(a, i, separator, finalSeparator, default, textForNull) */ Fixed example array values

[[Category:Analytica User Guide]]
[[Category: Text Functions]]
<breadcrumbs>Analytica User Guide > Text, Date, Math, and Financial Functions > {{PAGENAME}}</breadcrumbs>

These functions work with [[text values]] (sometimes known as strings), available in the built-in Text library.

__TOC__

==Asc(t)==

Returns the numeric character code of the first character in text value «t». This is occasionally useful, for example to understand the alphabetic ordering of text values. Unicode characters may have values greater that 255.

:Asc('d') → 100
:Asc('δ') → 948 { or, in hex, 0x3b4 }

See also [[Asc]](t).

==Chr(n)==
Returns the character corresponding to the numeric unicode code «n». [[Chr]]() and [[Asc]]() are inverses of each other, for example:

:<code>Chr(65) → 'A', Asc(Chr(65)) → 65</code>
:<code>Asc('A') → 65, Chr(Asc('A')) → 'A'</code>

[[Chr]]() is useful for creating characters that cannot easily be typed, such as ''Tab'', which is <code>Chr(9)</code> and ''carriage return (CR)'', which is <code>Chr(13)</code>. For example, if you read in a text file, <code>x</code>, you can use
<code>[[SplitText]](x, Chr(13))</code> to generate an array of lines from a multiline text file.

==TextLength(t)==
Returns the number of characters in text «t».

See also [[TextLength]]().

:<code>TextLength('supercalifragilisticexpialidocious') → 34</code>

==SelectText(t, m, n)==
Returns text containing the «m»'th through the «n»'th character of text «t» (where the first character is «m»=1). If you omit «n» it returns characters from the «m»'th through the end of «t».

See also [[SelectText]]().

:<code>SelectText('One or two', 1, 3) → 'One'</code>
:<code>SelectText('One or two', 8) → 'two'</code>

==FindInText(substr, text, ''start, caseInsensitive, re, return, subpattern, repeat, repeatSubpattern, repeatIndex'')==
Returns the position of the first occurrence of «substr» within «text», as the number of characters to the first character of text. If it can't find «substr» in text, it returns 0.

:<code>Variable People := 'Amy, Betty, Carla'</code>
:<code>FindInText('Amy', People) → 1</code>
:<code>FindInText('Betty', People) → 6</code>
:<code>FindInText('Fred', People) → 0</code>

=== Optional parameters ===

==== CaseInsensitive ====
[[FindInText]]() is case-sensitive unless the optional parameter «caseInsensitive» is true:
:<code>FindInText('amy', People) → 0</code>
:<code>FindInText('amy', People, caseInsensitive: true) → 1</code>

==== Start ====
The optional third parameter, «start», specifies the position to start searching at, for example, if you want to find a second occurrence of «substr» after you have found the first one.

:<code>FindInText('i','Supercalifragilisticexpialidocious') → 9</code>
:<code>FindInText('i','Supercalifragilisticexpialidocious', 10) → 14</code>

==== Repeat, RepeatIndex ====
Normally [[FindInText]]() returns information on the first match, but by using any of the three optional repeat parameters can be used to find all matches in text. When it finds multiple matches, the result is an array. If you specify<code>repeat: true</code>, the resulthas a local index named <code>.Repeat</code> with elements <code>1..n</code>.

Alternatively, you can specify a preexisting index as «repeatIndex» parameter. If that index has ''n'' elements, it returns only the first ''n'' matches.

This example parses XML text, returning an array of ages with a local index named «.Name», where the labels of the local index are the names of each person:

:<code>FindInText('<person.*?name = "(?<name>(.*?))".*?>.*?' & '<age>(?<age>.*?)</age>.*?' & '</person>', xmlText, re: true, return: 'S', repeatSubpattern: 'name', subpattern: 'age')</code>

==== Re (Regular expression), Return, and Subpattern ====

If you set optional parameter, «re», to <code>True,</code>it interprets «substr» as a ''regular expression''. The regular expression language is widely used (not just in Analytica) to specify match criteria for text. It offers "wild cards" that match any letter, digit, or other character, identify separate words, and a lot more. See [[Regular expression]]s for details.

Parentheses within a regular expression denote subpatterns, numbered in a depth first fashion. Subpatterns can also be named using the regular expression format “<code>(?<name>...)</code>”. You can the match information for any subpattern by specifying the subpattern number or subpattern name in the optional «subpattern» parameter.

:<code>FindInText('d.*T', 'FindInText', re:1) → 4</code>
:<code>FindInText('d.*T', 'FindInText', re: 1, return:['L', 'S']) → [4, 'dInT']</code>
:<code>FindInText('(\d\d\d)-(\d\d\d\d)', '650-212-1212', re:1, return:'S', subpattern:[0, 1, 2]) → ['212-1212', ’212’, ’1212’]</code>
:<code>FindInText('a*(?<bcd>b+(c+)(d*))','zyabdaabbcccfd', re:1, subpattern:['bcd', 0, 1, 2, 3]) → [8, 6, 8, 10, 13]</code>

The «return» parameter alters what is returned, according to what letter you provide as the parameter:

* ‘P’ (or ‘Position’): The position of the matching text or subpattern (default)
* ‘L’ (or ‘Length’): The length of the matching text or subpattern.
* 'S’ (or ‘Subpattern’): The text matched the regular expression or subpattern.
* ‘#’ (or ‘#Subpatterns’): The number of subpatterns in the regular expression.

==TextTrim(t, ''leftOnly, rightOnly, trimChars'')==
Removes leading and trailing spaces from the text «t».
:<code>TextTrim(' Hello World ') → 'Hello World'</code>

Set optional parameter «leftOnly» to True to remove only preceding spaces, or set «rightOnly» to True to remove only followingspaces:
:<code>TextTrim(' Hello World ', leftOnly: True) → 'Hello World'</code>
:<code>TextTrim(' Hello World ', rightOnly: True) → ' Hello World'</code>

To remove characters other than spaces, specify those characters in a text for the optional «trimChars» parameter:
:<code>TextTrim(' [One, Two, Three] ', trimChars: ' []') → 'One, Two, Three'</code>

==TextReplace(text, pattern, substr, ''all, caseInsensitive, re'')==
Returns text with the first occurrence of «pattern» replaced by «substr».

<code>TextReplace('StringReplace, StringLength', 'String', 'Text') → 'TextReplace, StringLength'</code>

If «all» is <code>True</code>, it returns «text» with ''all'' occurrences of text «pattern» replaced by «subst».
:<code>TextReplace('StringReplace, StringLength', 'String', 'Text', All: True) → 'TextReplace, TextLength'</code>
Matches are case-sensitive unless «caseInsensitive» is <code>True</code>.

==== Re (Regular expression) ====
When the optional «re» parameter is <code>True</code>, it treats «pattern» as a [[regular expression]]. In this mode, it replaces the character sequence <code>\0</code> in «subst» by the matching text, and it replaces <code>\1, \2, ..., \9</code> by the subtext matched by the corresponding numbered subpattern in the regular expression. The character sequence <code>''<name>''</code> in «subst» is replaced by the subtext matched to the indicated named subpattern.

:<code>TextReplace('Hello world', '\w+', '«\0»', all:True, re: True) → '«Hello» «world»'</code>
:<code>TextReplace('Hello world', '(.{1, 7}).*', '\1…', re: True) → 'Hello w…'</code>
:<code>TextReplace(text: 'swap first and last', pattern: '(?<first>\w+)(?<mid>.*)(?<last>\b\w+)', subst:'<last><mid><first>', re: True) → 'last first and swap’</code>
:<code>TextReplace('swap first and last', '(\w)(\w*)(\w)', '\3\2\1', re: 1, all: 1 ) → 'pwas tirsf dna tasl'</code>

==Joining Text: a & b==
The [[Text_Concatenation_Operator%3A_%26|&]] operator joins (concatenates) two text values to form a single text value, for example:

:<code>'What is the' & ' number' & '?' → 'What is the number?'</code>

If one or both operands are numbers, it converts them to text using the number format of the variable whose definition contains this function call (or the default suffix format if none is set), for example:

:<code>'The number is ' & 10^8 → 'The number is 100M'</code>

This is also useful for converting (or “coercing”) numbers to text. The [[NumberToText]] function is also useful for converting numbers to text when you want to specify the number format explicitly.

The result of concatenation of text with the special value [[Null]] changed in the [[Analytica 5.0]] release:
:<code>'The value is ' & Null → 'The value is Null'</code>     ''{in [[Analytica 5.0]] and later}''
:<code>'The value is ' & Null → «null»</code>     ''{in [[Analytica 4.6]] and earlier}''

==JoinText(a, i, ''separator, finalSeparator, default, textForNull'')==
Returns the elements of array «a» joined together into a single text value over index «i». If elements of «a» are numeric, [[JoinText]]() first converts them to text using the number format settings for the variable whose definition contains this function call. For example:

:<code>I := ['A', 'B', 'C']</code>
:<code>JoinText(I, I) → 'ABC'</code>
:<code>A := Array(I, ['VW', 'Honda', 'BMW'])</code>
:<code>B := Array(I, ['one', Null, 'two'])</code>
:<code>JoinText(A, I) → 'VWHondaBMW'</code>

If the optional parameter «separator» is specified, it is inserted as a separator between successive elements, for example:

:<code>JoinText(A, I, ', ') → 'VW, Honda, BMW'</code>

The optional parameter «finalSeparator», if present, specifies a different separator between the second-to-last and last elements of «a».

:<code>JoinText(A, I, '; ', '; and ') → 'VW; Honda; and BMW'</code>

Null values in «a» are ignored unless the optional parameter «textForNull» is specified.

:<code>JoinText(B, I, ', ') → 'one, two'</code>
:<code>JoinText(B, I, ', ', textForNull: '') → 'one, , two'</code>
:<code>JoinText(B, I, ', ' , textForNull: 'NULL') → 'one, NULL, two'</code>

The optional «default» parameter is returned when all values are ignored, or «a» has a zero length.

:<code>JoinText([Null, Null, Null], default: Null) → «null»</code>

==SplitText(text, separator, ''caseInsensitive, re'')==
Returns a list of text values formed by splitting the elements of text value text at each occurrence of separator «separator». For example:

:<code>SplitText('VW, Honda, BMW', ', ') → ['VW', 'Honda', 'BMW']</code>

[[SplitText]]() is the inverse of [[JoinText]](), if you use the same separators. For example:

:<code>Var x := SplitText('Humpty Dumpty sat on a wall.', ' ') → ['Humpty', 'Dumpty', 'sat', 'on', 'a', 'wall.']</code>
:<code>JoinText(x, , ' ') → 'Humpty Dumpty sat on a wall.'</code>

When «separator» contains letters, setting «caseInsensitive» to <code>True</code> matches in a lower/uppercase-insensitive manner. When the «re» parameter is <code>True</code>, separator is interpreted as a Perl-compatible [[regular expression]].

:<code>Variable s := 'Yes, Virginia. There is a Santa Claus!'</code>
:<code>SplitText(s, '[\s, \.!]+', re: 1) → ['Yes', 'Virginia', 'There', 'is', 'a', 'Santa', 'Claus', '']</code>
:<code>SplitText(TextTrim(s, trimChars: ' , .!'), '[\s, \.!]+', re:1) → ['Yes', 'Virginia', 'There', 'is', 'a', 'Santa', 'Claus']</code>

<tip title="Tip> With [[SplitText]](), «text» must be a single text value, not an array. Otherwise, it might generate an array of arrays of different length. See [[Ensuring Array Abstraction|Functions expecting atomic parameters]] on what to do if you want apply it to an array.
</Tip>

==TextLowerCase(t)==
[[TextLowerCase]]() returns the text «t» with all letters as lowercase. For example:

:<code>TextLowerCase('What does XML mean?') → 'what does xml mean?'</code>

==TextUpperCase(t)==
[[TextUpperCase]]() returns the text «t» with all letters as uppercase. For example:

:<code>TextUpperCase('What does XML mean?') → 'WHAT DOES XML MEAN?'</code>

==TextSentenceCase(Text, ''preserveUC'')==
[[TextSentenceCase]]() returns the text «t» with the first character (if a letter) as uppercase, and any other letters as lowercase. For example:

:<code>TextSentenceCase('mary ann FRED Maylene') → 'Mary ann fred maylene'</code>
:<code>TextSentenceCase(SplitText('mary ann FRED Maylene', ' ')) → ['Mary', 'Ann', 'Fred', 'Maylene']</code>
:<code>TextSentenceCase('they are Fred and Maylene', true) → 'They are Fred and Maylene'</code>

==NumberToText(x, format)==

NumberToText() converts number «x» to text using the specified «format». It provides all the settings and options available in the [[Number formats]] dialog for displaying a number (including a date number).

Possible values for «format» are: <code>'Suffix', 'Exponential', 'Fixed Point', 'Integer', 'Percent', 'Date', 'Boolean'</code>, or <code>'Hexadecimal'</code>. You can just use the first letter of a format to keep it brief:

:<code>NumberToText(3.45M, ['S', 'E', 'F', 'I', 'H']) → ['3.45M', '3.45.e+006', '3450000', '3450000', '0x34a490']</code>
:<code>NumberToText(0.0012, ['S', 'E', 'F', 'P']) → ['1.2m', '1.2e-003', '0', 0.12%']</code>

NumberToText() offers these optional parameters:

*«digits» specifies the precision for Suffix and Exponential formats, and the digits to the right of the decimal for Fixed Point and Percent formats, for example:

:<code>NumberToText(Pi, 'Suffix', digits: 5) → '3.1416'</code>
:<code>NumberToText(Pi, 'Fixed Point', digits: 5) → '3.14159'</code>
:<code>NumberToText(Pi, 'Percent', digits: 5) → '314.15927%'</code>

* «showZeros» forces the inclusion of trailing zeros:

:<code>NumberToText(1/4, 'Percent', digits: 2, showZeros: True) → '25.00%'</code>

Set «thousandsSeparators» to <code>True</code> to separate digits into groups of three:

:<code>NumberToText(7^12,'I', thousandsSeparators: True) → '13,841, 287, 201'</code>

* «currency» specifies a template with the currency symbol and its placement relative to the number and the minus sign.

:<code>NumberToText(-372, 'F', currency: ['-£#', 'US$-#', '#£-', '($#)']) → ['-£372', 'US$-372', '372£-', '($372)']</code>

* «dateFormat» provides a date format template for converting [[date numbers]] to text:

:<code>NumberToText(Today(), dateFormat: 'yyyy MMMM dd (wwww)') → '2013 July 01 (Monday)'</code>

* «fullPrecision»: Set this to true, to include all digits to ensure that the full precision of the number.

:<code>NumberToText(Pi, fullPrecision: True) → '3.141592653589793'</code>

== ParseNumber(text, ''badVal'') ==

Parses a text value into a number. (For dates, use [[ParseDate]]()). The result is independent of the number format setting. Values that are already numeric are returned. If the number is unparseable, it returns <code>Null</code>, unless you specify a different value to the optional parameter «badVal».

:<code>ParseNumber('12.43K') → 12.43K</code>
:<code>ParseNumber('hello') → «null»</code>
:<code>ParseNumber(14.3) → 14.3</code>

If you use <code>ParseNumber(x, x)</code> it will simply return any unparseable text values in «x» as the original text value:

:<code>VAR x := ['3, 214', 14, 'foo'] DO ParseNumber(x, x) → [ 3214, 14, 'foo']</code>

==TextCharacterEncode(type,text)==
(''New to [[Analytica 5.0]]'' ) Transforms «text» into an alternative text encoding specified by «type». The text can be ''URL encoded'' for inclusion in a URL or ''URL decoded'', ''XML encoded'', put into one of the four normalized unicode forms, or converted to or from a UTF-8 encoding. See [[TextCharacterEncode]].
:<code>TextCharacterEncode('UTF-8', 'γσh') → 'Î³Ïh'</code>
:<code>TextCharacterDecode('-UTF-8','Î³Ïh') → 'γσh'</code>
:<code>TextCharacterEncode('URL','3:4 = 3/4 & 1/2 = 0.5') → '3%3A4+%3D+3%2F4+%26+1%2F2+%3D+0.5'</code>

== TextDistance(t1,t2) ==
(''New to [[Analytica 5.0]]'' ) Returns a distance measure indicating how different two text values are. The result is the number of edit steps (substitutions, deletions, insertions, etc.) are required to transform «t1» into «t2». Many optional parameters can be used to specify which editing operations are allowed (see [[TextDistance]]()), allowing various standard distance measures including Levenshtein distance, Demerau-Levenshtein distance, Hamming distance, and Longest common subsequence among others.

:<code>[[TextDistance]]("portland", "orlando") → 3</code>
::Note: <code>"portland" → "ortland" → "orland" → "orlando"</code>

== Data file parsing and creation functions ==
When you exchange data with other applications (which in generally requires the [[Analytica Enterprise]] edition or better), you may need to parse the data, or put your data into a given format. Commonly used formats include CSV (which stands for Comma Separated Values, but includes other separators such as tabs), XML and JSON. The following functions can be used to parse or create data in these formats:
* [[ParseCSV]] and [[MakeCSV]]
* [[ParseJSON]] and [[MakeJSON]]
* The Microsoft XML DOM parser. See [[Example_Models#Extracting_Data_from_an_XML_file|Parsing an XML file]]. This uses [[COM Integration]] and requires the [[Analytica Enterprise]] edition.

:<code>[[ParseCSV]]( [[ReadTextFile]]( "MyData.csv" ) )</code> → { 2-D array indexed by local indexes <code>.Column</code> and <code>.Row</code>}

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Regular Expressions]]
* [[Asc]]()
* [[Chr]]()
* [[TextLength]]()
* [[SelectText]]()
* [[ FindInText]]()
* [[TextTrim]]()
* [[TextReplace]]()
* [[Text Concatenation Operator: &]]
* [[JoinText]]()
* [[SplitText]]()
* [[TextLowerCase]]()
* [[TextUpperCase]]()
* [[TextSentenceCase]]()
* [[NumberToText]]()
* [[TextDistance]]()
* [[TextCharacterEncode]]()
* [[Numbers and text]]
* [[Converting Numbers to Text]]
* [[ParseNumber]]()
* [[Model File Character Encoding]]
* [[Read and write text files]]
* [[Files and Editing]]
* [[Multiple formats in one table]]

</div>

<footer>Text, Date, Math, and Financial Functions / {{PAGENAME}} / Date functions</footer>

Text functions

2025-04-08T04:39:16Z

Fredbrunt: /* JoinText(a, i, separator, finalSeparator, default, textForNull) */

[[Category:Analytica User Guide]]
[[Category: Text Functions]]
<breadcrumbs>Analytica User Guide > Text, Date, Math, and Financial Functions > {{PAGENAME}}</breadcrumbs>

These functions work with [[text values]] (sometimes known as strings), available in the built-in Text library.

__TOC__

==Asc(t)==

Returns the numeric character code of the first character in text value «t». This is occasionally useful, for example to understand the alphabetic ordering of text values. Unicode characters may have values greater that 255.

:Asc('d') → 100
:Asc('δ') → 948 { or, in hex, 0x3b4 }

See also [[Asc]](t).

==Chr(n)==
Returns the character corresponding to the numeric unicode code «n». [[Chr]]() and [[Asc]]() are inverses of each other, for example:

:<code>Chr(65) → 'A', Asc(Chr(65)) → 65</code>
:<code>Asc('A') → 65, Chr(Asc('A')) → 'A'</code>

[[Chr]]() is useful for creating characters that cannot easily be typed, such as ''Tab'', which is <code>Chr(9)</code> and ''carriage return (CR)'', which is <code>Chr(13)</code>. For example, if you read in a text file, <code>x</code>, you can use
<code>[[SplitText]](x, Chr(13))</code> to generate an array of lines from a multiline text file.

==TextLength(t)==
Returns the number of characters in text «t».

See also [[TextLength]]().

:<code>TextLength('supercalifragilisticexpialidocious') → 34</code>

==SelectText(t, m, n)==
Returns text containing the «m»'th through the «n»'th character of text «t» (where the first character is «m»=1). If you omit «n» it returns characters from the «m»'th through the end of «t».

See also [[SelectText]]().

:<code>SelectText('One or two', 1, 3) → 'One'</code>
:<code>SelectText('One or two', 8) → 'two'</code>

==FindInText(substr, text, ''start, caseInsensitive, re, return, subpattern, repeat, repeatSubpattern, repeatIndex'')==
Returns the position of the first occurrence of «substr» within «text», as the number of characters to the first character of text. If it can't find «substr» in text, it returns 0.

:<code>Variable People := 'Amy, Betty, Carla'</code>
:<code>FindInText('Amy', People) → 1</code>
:<code>FindInText('Betty', People) → 6</code>
:<code>FindInText('Fred', People) → 0</code>

=== Optional parameters ===

==== CaseInsensitive ====
[[FindInText]]() is case-sensitive unless the optional parameter «caseInsensitive» is true:
:<code>FindInText('amy', People) → 0</code>
:<code>FindInText('amy', People, caseInsensitive: true) → 1</code>

==== Start ====
The optional third parameter, «start», specifies the position to start searching at, for example, if you want to find a second occurrence of «substr» after you have found the first one.

:<code>FindInText('i','Supercalifragilisticexpialidocious') → 9</code>
:<code>FindInText('i','Supercalifragilisticexpialidocious', 10) → 14</code>

==== Repeat, RepeatIndex ====
Normally [[FindInText]]() returns information on the first match, but by using any of the three optional repeat parameters can be used to find all matches in text. When it finds multiple matches, the result is an array. If you specify<code>repeat: true</code>, the resulthas a local index named <code>.Repeat</code> with elements <code>1..n</code>.

Alternatively, you can specify a preexisting index as «repeatIndex» parameter. If that index has ''n'' elements, it returns only the first ''n'' matches.

This example parses XML text, returning an array of ages with a local index named «.Name», where the labels of the local index are the names of each person:

:<code>FindInText('<person.*?name = "(?<name>(.*?))".*?>.*?' & '<age>(?<age>.*?)</age>.*?' & '</person>', xmlText, re: true, return: 'S', repeatSubpattern: 'name', subpattern: 'age')</code>

==== Re (Regular expression), Return, and Subpattern ====

If you set optional parameter, «re», to <code>True,</code>it interprets «substr» as a ''regular expression''. The regular expression language is widely used (not just in Analytica) to specify match criteria for text. It offers "wild cards" that match any letter, digit, or other character, identify separate words, and a lot more. See [[Regular expression]]s for details.

Parentheses within a regular expression denote subpatterns, numbered in a depth first fashion. Subpatterns can also be named using the regular expression format “<code>(?<name>...)</code>”. You can the match information for any subpattern by specifying the subpattern number or subpattern name in the optional «subpattern» parameter.

:<code>FindInText('d.*T', 'FindInText', re:1) → 4</code>
:<code>FindInText('d.*T', 'FindInText', re: 1, return:['L', 'S']) → [4, 'dInT']</code>
:<code>FindInText('(\d\d\d)-(\d\d\d\d)', '650-212-1212', re:1, return:'S', subpattern:[0, 1, 2]) → ['212-1212', ’212’, ’1212’]</code>
:<code>FindInText('a*(?<bcd>b+(c+)(d*))','zyabdaabbcccfd', re:1, subpattern:['bcd', 0, 1, 2, 3]) → [8, 6, 8, 10, 13]</code>

The «return» parameter alters what is returned, according to what letter you provide as the parameter:

* ‘P’ (or ‘Position’): The position of the matching text or subpattern (default)
* ‘L’ (or ‘Length’): The length of the matching text or subpattern.
* 'S’ (or ‘Subpattern’): The text matched the regular expression or subpattern.
* ‘#’ (or ‘#Subpatterns’): The number of subpatterns in the regular expression.

==TextTrim(t, ''leftOnly, rightOnly, trimChars'')==
Removes leading and trailing spaces from the text «t».
:<code>TextTrim(' Hello World ') → 'Hello World'</code>

Set optional parameter «leftOnly» to True to remove only preceding spaces, or set «rightOnly» to True to remove only followingspaces:
:<code>TextTrim(' Hello World ', leftOnly: True) → 'Hello World'</code>
:<code>TextTrim(' Hello World ', rightOnly: True) → ' Hello World'</code>

To remove characters other than spaces, specify those characters in a text for the optional «trimChars» parameter:
:<code>TextTrim(' [One, Two, Three] ', trimChars: ' []') → 'One, Two, Three'</code>

==TextReplace(text, pattern, substr, ''all, caseInsensitive, re'')==
Returns text with the first occurrence of «pattern» replaced by «substr».

<code>TextReplace('StringReplace, StringLength', 'String', 'Text') → 'TextReplace, StringLength'</code>

If «all» is <code>True</code>, it returns «text» with ''all'' occurrences of text «pattern» replaced by «subst».
:<code>TextReplace('StringReplace, StringLength', 'String', 'Text', All: True) → 'TextReplace, TextLength'</code>
Matches are case-sensitive unless «caseInsensitive» is <code>True</code>.

==== Re (Regular expression) ====
When the optional «re» parameter is <code>True</code>, it treats «pattern» as a [[regular expression]]. In this mode, it replaces the character sequence <code>\0</code> in «subst» by the matching text, and it replaces <code>\1, \2, ..., \9</code> by the subtext matched by the corresponding numbered subpattern in the regular expression. The character sequence <code>''<name>''</code> in «subst» is replaced by the subtext matched to the indicated named subpattern.

:<code>TextReplace('Hello world', '\w+', '«\0»', all:True, re: True) → '«Hello» «world»'</code>
:<code>TextReplace('Hello world', '(.{1, 7}).*', '\1…', re: True) → 'Hello w…'</code>
:<code>TextReplace(text: 'swap first and last', pattern: '(?<first>\w+)(?<mid>.*)(?<last>\b\w+)', subst:'<last><mid><first>', re: True) → 'last first and swap’</code>
:<code>TextReplace('swap first and last', '(\w)(\w*)(\w)', '\3\2\1', re: 1, all: 1 ) → 'pwas tirsf dna tasl'</code>

==Joining Text: a & b==
The [[Text_Concatenation_Operator%3A_%26|&]] operator joins (concatenates) two text values to form a single text value, for example:

:<code>'What is the' & ' number' & '?' → 'What is the number?'</code>

If one or both operands are numbers, it converts them to text using the number format of the variable whose definition contains this function call (or the default suffix format if none is set), for example:

:<code>'The number is ' & 10^8 → 'The number is 100M'</code>

This is also useful for converting (or “coercing”) numbers to text. The [[NumberToText]] function is also useful for converting numbers to text when you want to specify the number format explicitly.

The result of concatenation of text with the special value [[Null]] changed in the [[Analytica 5.0]] release:
:<code>'The value is ' & Null → 'The value is Null'</code>     ''{in [[Analytica 5.0]] and later}''
:<code>'The value is ' & Null → «null»</code>     ''{in [[Analytica 4.6]] and earlier}''

==JoinText(a, i, ''separator, finalSeparator, default, textForNull'')==
Returns the elements of array «a» joined together into a single text value over index «i». If elements of «a» are numeric, [[JoinText]]() first converts them to text using the number format settings for the variable whose definition contains this function call. For example:

:<code>I := ['A', 'B', 'C']</code>
:<code>JoinText(I, I) → 'ABC'</code>
:<code>A := Array(I, ['VW', 'Honda', 'BMW'])</code>
:<code>B := Array(I, ['VW', Null, 'BMW'])</code>
:<code>JoinText(A, I) → 'VWHondaBMW'</code>

If the optional parameter «separator» is specified, it is inserted as a separator between successive elements, for example:

:<code>JoinText(A, I, ', ') → 'VW, Honda, BMW'</code>

The optional parameter «finalSeparator», if present, specifies a different separator between the second-to-last and last elements of «a».

:<code>JoinText(A, I, '; ', '; and ') → 'VW; Honda; and BMW'</code>

Null values in «a» are ignored unless the optional parameter «textForNull» is specified.

:<code>JoinText(B, I, ', ') → 'one, two'</code>
:<code>JoinText(B, I, ', ', textForNull: '') → 'one, , two'</code>
:<code>JoinText(B, I, ', ' , textForNull: 'NULL') → 'one, NULL, two'</code>

The optional «default» parameter is returned when all values are ignored, or «a» has a zero length.

:<code>JoinText([Null, Null, Null], default: Null) → «null»</code>

==SplitText(text, separator, ''caseInsensitive, re'')==
Returns a list of text values formed by splitting the elements of text value text at each occurrence of separator «separator». For example:

:<code>SplitText('VW, Honda, BMW', ', ') → ['VW', 'Honda', 'BMW']</code>

[[SplitText]]() is the inverse of [[JoinText]](), if you use the same separators. For example:

:<code>Var x := SplitText('Humpty Dumpty sat on a wall.', ' ') → ['Humpty', 'Dumpty', 'sat', 'on', 'a', 'wall.']</code>
:<code>JoinText(x, , ' ') → 'Humpty Dumpty sat on a wall.'</code>

When «separator» contains letters, setting «caseInsensitive» to <code>True</code> matches in a lower/uppercase-insensitive manner. When the «re» parameter is <code>True</code>, separator is interpreted as a Perl-compatible [[regular expression]].

:<code>Variable s := 'Yes, Virginia. There is a Santa Claus!'</code>
:<code>SplitText(s, '[\s, \.!]+', re: 1) → ['Yes', 'Virginia', 'There', 'is', 'a', 'Santa', 'Claus', '']</code>
:<code>SplitText(TextTrim(s, trimChars: ' , .!'), '[\s, \.!]+', re:1) → ['Yes', 'Virginia', 'There', 'is', 'a', 'Santa', 'Claus']</code>

<tip title="Tip> With [[SplitText]](), «text» must be a single text value, not an array. Otherwise, it might generate an array of arrays of different length. See [[Ensuring Array Abstraction|Functions expecting atomic parameters]] on what to do if you want apply it to an array.
</Tip>

==TextLowerCase(t)==
[[TextLowerCase]]() returns the text «t» with all letters as lowercase. For example:

:<code>TextLowerCase('What does XML mean?') → 'what does xml mean?'</code>

==TextUpperCase(t)==
[[TextUpperCase]]() returns the text «t» with all letters as uppercase. For example:

:<code>TextUpperCase('What does XML mean?') → 'WHAT DOES XML MEAN?'</code>

==TextSentenceCase(Text, ''preserveUC'')==
[[TextSentenceCase]]() returns the text «t» with the first character (if a letter) as uppercase, and any other letters as lowercase. For example:

:<code>TextSentenceCase('mary ann FRED Maylene') → 'Mary ann fred maylene'</code>
:<code>TextSentenceCase(SplitText('mary ann FRED Maylene', ' ')) → ['Mary', 'Ann', 'Fred', 'Maylene']</code>
:<code>TextSentenceCase('they are Fred and Maylene', true) → 'They are Fred and Maylene'</code>

==NumberToText(x, format)==

NumberToText() converts number «x» to text using the specified «format». It provides all the settings and options available in the [[Number formats]] dialog for displaying a number (including a date number).

Possible values for «format» are: <code>'Suffix', 'Exponential', 'Fixed Point', 'Integer', 'Percent', 'Date', 'Boolean'</code>, or <code>'Hexadecimal'</code>. You can just use the first letter of a format to keep it brief:

:<code>NumberToText(3.45M, ['S', 'E', 'F', 'I', 'H']) → ['3.45M', '3.45.e+006', '3450000', '3450000', '0x34a490']</code>
:<code>NumberToText(0.0012, ['S', 'E', 'F', 'P']) → ['1.2m', '1.2e-003', '0', 0.12%']</code>

NumberToText() offers these optional parameters:

*«digits» specifies the precision for Suffix and Exponential formats, and the digits to the right of the decimal for Fixed Point and Percent formats, for example:

:<code>NumberToText(Pi, 'Suffix', digits: 5) → '3.1416'</code>
:<code>NumberToText(Pi, 'Fixed Point', digits: 5) → '3.14159'</code>
:<code>NumberToText(Pi, 'Percent', digits: 5) → '314.15927%'</code>

* «showZeros» forces the inclusion of trailing zeros:

:<code>NumberToText(1/4, 'Percent', digits: 2, showZeros: True) → '25.00%'</code>

Set «thousandsSeparators» to <code>True</code> to separate digits into groups of three:

:<code>NumberToText(7^12,'I', thousandsSeparators: True) → '13,841, 287, 201'</code>

* «currency» specifies a template with the currency symbol and its placement relative to the number and the minus sign.

:<code>NumberToText(-372, 'F', currency: ['-£#', 'US$-#', '#£-', '($#)']) → ['-£372', 'US$-372', '372£-', '($372)']</code>

* «dateFormat» provides a date format template for converting [[date numbers]] to text:

:<code>NumberToText(Today(), dateFormat: 'yyyy MMMM dd (wwww)') → '2013 July 01 (Monday)'</code>

* «fullPrecision»: Set this to true, to include all digits to ensure that the full precision of the number.

:<code>NumberToText(Pi, fullPrecision: True) → '3.141592653589793'</code>

== ParseNumber(text, ''badVal'') ==

Parses a text value into a number. (For dates, use [[ParseDate]]()). The result is independent of the number format setting. Values that are already numeric are returned. If the number is unparseable, it returns <code>Null</code>, unless you specify a different value to the optional parameter «badVal».

:<code>ParseNumber('12.43K') → 12.43K</code>
:<code>ParseNumber('hello') → «null»</code>
:<code>ParseNumber(14.3) → 14.3</code>

If you use <code>ParseNumber(x, x)</code> it will simply return any unparseable text values in «x» as the original text value:

:<code>VAR x := ['3, 214', 14, 'foo'] DO ParseNumber(x, x) → [ 3214, 14, 'foo']</code>

==TextCharacterEncode(type,text)==
(''New to [[Analytica 5.0]]'' ) Transforms «text» into an alternative text encoding specified by «type». The text can be ''URL encoded'' for inclusion in a URL or ''URL decoded'', ''XML encoded'', put into one of the four normalized unicode forms, or converted to or from a UTF-8 encoding. See [[TextCharacterEncode]].
:<code>TextCharacterEncode('UTF-8', 'γσh') → 'Î³Ïh'</code>
:<code>TextCharacterDecode('-UTF-8','Î³Ïh') → 'γσh'</code>
:<code>TextCharacterEncode('URL','3:4 = 3/4 & 1/2 = 0.5') → '3%3A4+%3D+3%2F4+%26+1%2F2+%3D+0.5'</code>

== TextDistance(t1,t2) ==
(''New to [[Analytica 5.0]]'' ) Returns a distance measure indicating how different two text values are. The result is the number of edit steps (substitutions, deletions, insertions, etc.) are required to transform «t1» into «t2». Many optional parameters can be used to specify which editing operations are allowed (see [[TextDistance]]()), allowing various standard distance measures including Levenshtein distance, Demerau-Levenshtein distance, Hamming distance, and Longest common subsequence among others.

:<code>[[TextDistance]]("portland", "orlando") → 3</code>
::Note: <code>"portland" → "ortland" → "orland" → "orlando"</code>

== Data file parsing and creation functions ==
When you exchange data with other applications (which in generally requires the [[Analytica Enterprise]] edition or better), you may need to parse the data, or put your data into a given format. Commonly used formats include CSV (which stands for Comma Separated Values, but includes other separators such as tabs), XML and JSON. The following functions can be used to parse or create data in these formats:
* [[ParseCSV]] and [[MakeCSV]]
* [[ParseJSON]] and [[MakeJSON]]
* The Microsoft XML DOM parser. See [[Example_Models#Extracting_Data_from_an_XML_file|Parsing an XML file]]. This uses [[COM Integration]] and requires the [[Analytica Enterprise]] edition.

:<code>[[ParseCSV]]( [[ReadTextFile]]( "MyData.csv" ) )</code> → { 2-D array indexed by local indexes <code>.Column</code> and <code>.Row</code>}

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Regular Expressions]]
* [[Asc]]()
* [[Chr]]()
* [[TextLength]]()
* [[SelectText]]()
* [[ FindInText]]()
* [[TextTrim]]()
* [[TextReplace]]()
* [[Text Concatenation Operator: &]]
* [[JoinText]]()
* [[SplitText]]()
* [[TextLowerCase]]()
* [[TextUpperCase]]()
* [[TextSentenceCase]]()
* [[NumberToText]]()
* [[TextDistance]]()
* [[TextCharacterEncode]]()
* [[Numbers and text]]
* [[Converting Numbers to Text]]
* [[ParseNumber]]()
* [[Model File Character Encoding]]
* [[Read and write text files]]
* [[Files and Editing]]
* [[Multiple formats in one table]]

</div>

<footer>Text, Date, Math, and Financial Functions / {{PAGENAME}} / Date functions</footer>

Text functions

2025-04-03T05:02:18Z

Fredbrunt: /* Re (Regular expression), Return, and Subpattern */ Fixed bad single quote character. Replaced with proper single quote character that works in Analytica.

[[Category:Analytica User Guide]]
[[Category: Text Functions]]
<breadcrumbs>Analytica User Guide > Text, Date, Math, and Financial Functions > {{PAGENAME}}</breadcrumbs>

These functions work with [[text values]] (sometimes known as strings), available in the built-in Text library.

__TOC__

==Asc(t)==

Returns the numeric character code of the first character in text value «t». This is occasionally useful, for example to understand the alphabetic ordering of text values. Unicode characters may have values greater that 255.

:Asc('d') → 100
:Asc('δ') → 948 { or, in hex, 0x3b4 }

See also [[Asc]](t).

==Chr(n)==
Returns the character corresponding to the numeric unicode code «n». [[Chr]]() and [[Asc]]() are inverses of each other, for example:

:<code>Chr(65) → 'A', Asc(Chr(65)) → 65</code>
:<code>Asc('A') → 65, Chr(Asc('A')) → 'A'</code>

[[Chr]]() is useful for creating characters that cannot easily be typed, such as ''Tab'', which is <code>Chr(9)</code> and ''carriage return (CR)'', which is <code>Chr(13)</code>. For example, if you read in a text file, <code>x</code>, you can use
<code>[[SplitText]](x, Chr(13))</code> to generate an array of lines from a multiline text file.

==TextLength(t)==
Returns the number of characters in text «t».

See also [[TextLength]]().

:<code>TextLength('supercalifragilisticexpialidocious') → 34</code>

==SelectText(t, m, n)==
Returns text containing the «m»'th through the «n»'th character of text «t» (where the first character is «m»=1). If you omit «n» it returns characters from the «m»'th through the end of «t».

See also [[SelectText]]().

:<code>SelectText('One or two', 1, 3) → 'One'</code>
:<code>SelectText('One or two', 8) → 'two'</code>

==FindInText(substr, text, ''start, caseInsensitive, re, return, subpattern, repeat, repeatSubpattern, repeatIndex'')==
Returns the position of the first occurrence of «substr» within «text», as the number of characters to the first character of text. If it can't find «substr» in text, it returns 0.

:<code>Variable People := 'Amy, Betty, Carla'</code>
:<code>FindInText('Amy', People) → 1</code>
:<code>FindInText('Betty', People) → 6</code>
:<code>FindInText('Fred', People) → 0</code>

=== Optional parameters ===

==== CaseInsensitive ====
[[FindInText]]() is case-sensitive unless the optional parameter «caseInsensitive» is true:
:<code>FindInText('amy', People) → 0</code>
:<code>FindInText('amy', People, caseInsensitive: true) → 1</code>

==== Start ====
The optional third parameter, «start», specifies the position to start searching at, for example, if you want to find a second occurrence of «substr» after you have found the first one.

:<code>FindInText('i','Supercalifragilisticexpialidocious') → 9</code>
:<code>FindInText('i','Supercalifragilisticexpialidocious', 10) → 14</code>

==== Repeat, RepeatIndex ====
Normally [[FindInText]]() returns information on the first match, but by using any of the three optional repeat parameters can be used to find all matches in text. When it finds multiple matches, the result is an array. If you specify<code>repeat: true</code>, the resulthas a local index named <code>.Repeat</code> with elements <code>1..n</code>.

Alternatively, you can specify a preexisting index as «repeatIndex» parameter. If that index has ''n'' elements, it returns only the first ''n'' matches.

This example parses XML text, returning an array of ages with a local index named «.Name», where the labels of the local index are the names of each person:

:<code>FindInText('<person.*?name = "(?<name>(.*?))".*?>.*?' & '<age>(?<age>.*?)</age>.*?' & '</person>', xmlText, re: true, return: 'S', repeatSubpattern: 'name', subpattern: 'age')</code>

==== Re (Regular expression), Return, and Subpattern ====

If you set optional parameter, «re», to <code>True,</code>it interprets «substr» as a ''regular expression''. The regular expression language is widely used (not just in Analytica) to specify match criteria for text. It offers "wild cards" that match any letter, digit, or other character, identify separate words, and a lot more. See [[Regular expression]]s for details.

Parentheses within a regular expression denote subpatterns, numbered in a depth first fashion. Subpatterns can also be named using the regular expression format “<code>(?<name>...)</code>”. You can the match information for any subpattern by specifying the subpattern number or subpattern name in the optional «subpattern» parameter.

:<code>FindInText('d.*T', 'FindInText', re:1) → 4</code>
:<code>FindInText('d.*T', 'FindInText', re: 1, return:['L', 'S']) → [4, 'dInT']</code>
:<code>FindInText('(\d\d\d)-(\d\d\d\d)', '650-212-1212', re:1, return:'S', subpattern:[0, 1, 2]) → ['212-1212', ’212’, ’1212’]</code>
:<code>FindInText('a*(?<bcd>b+(c+)(d*))','zyabdaabbcccfd', re:1, subpattern:['bcd', 0, 1, 2, 3]) → [8, 6, 8, 10, 13]</code>

The «return» parameter alters what is returned, according to what letter you provide as the parameter:

* ‘P’ (or ‘Position’): The position of the matching text or subpattern (default)
* ‘L’ (or ‘Length’): The length of the matching text or subpattern.
* 'S’ (or ‘Subpattern’): The text matched the regular expression or subpattern.
* ‘#’ (or ‘#Subpatterns’): The number of subpatterns in the regular expression.

==TextTrim(t, ''leftOnly, rightOnly, trimChars'')==
Removes leading and trailing spaces from the text «t».
:<code>TextTrim(' Hello World ') → 'Hello World'</code>

Set optional parameter «leftOnly» to True to remove only preceding spaces, or set «rightOnly» to True to remove only followingspaces:
:<code>TextTrim(' Hello World ', leftOnly: True) → 'Hello World'</code>
:<code>TextTrim(' Hello World ', rightOnly: True) → ' Hello World'</code>

To remove characters other than spaces, specify those characters in a text for the optional «trimChars» parameter:
:<code>TextTrim(' [One, Two, Three] ', trimChars: ' []') → 'One, Two, Three'</code>

==TextReplace(text, pattern, substr, ''all, caseInsensitive, re'')==
Returns text with the first occurrence of «pattern» replaced by «substr».

<code>TextReplace('StringReplace, StringLength', 'String', 'Text') → 'TextReplace, StringLength'</code>

If «all» is <code>True</code>, it returns «text» with ''all'' occurrences of text «pattern» replaced by «subst».
:<code>TextReplace('StringReplace, StringLength', 'String', 'Text', All: True) → 'TextReplace, TextLength'</code>
Matches are case-sensitive unless «caseInsensitive» is <code>True</code>.

==== Re (Regular expression) ====
When the optional «re» parameter is <code>True</code>, it treats «pattern» as a [[regular expression]]. In this mode, it replaces the character sequence <code>\0</code> in «subst» by the matching text, and it replaces <code>\1, \2, ..., \9</code> by the subtext matched by the corresponding numbered subpattern in the regular expression. The character sequence <code>''<name>''</code> in «subst» is replaced by the subtext matched to the indicated named subpattern.

:<code>TextReplace('Hello world', '\w+', '«\0»', all:True, re: True) → '«Hello» «world»'</code>
:<code>TextReplace('Hello world', '(.{1, 7}).*', '\1…', re: True) → 'Hello w…'</code>
:<code>TextReplace(text: 'swap first and last', pattern: '(?<first>\w+)(?<mid>.*)(?<last>\b\w+)', subst:'<last><mid><first>', re: True) → 'last first and swap’</code>
:<code>TextReplace('swap first and last', '(\w)(\w*)(\w)', '\3\2\1', re: 1, all: 1 ) → 'pwas tirsf dna tasl'</code>

==Joining Text: a & b==
The [[Text_Concatenation_Operator%3A_%26|&]] operator joins (concatenates) two text values to form a single text value, for example:

:<code>'What is the' & ' number' & '?' → 'What is the number?'</code>

If one or both operands are numbers, it converts them to text using the number format of the variable whose definition contains this function call (or the default suffix format if none is set), for example:

:<code>'The number is ' & 10^8 → 'The number is 100M'</code>

This is also useful for converting (or “coercing”) numbers to text. The [[NumberToText]] function is also useful for converting numbers to text when you want to specify the number format explicitly.

The result of concatenation of text with the special value [[Null]] changed in the [[Analytica 5.0]] release:
:<code>'The value is ' & Null → 'The value is Null'</code>     ''{in [[Analytica 5.0]] and later}''
:<code>'The value is ' & Null → «null»</code>     ''{in [[Analytica 4.6]] and earlier}''

==JoinText(a, i, ''separator, finalSeparator, default, textForNull'')==
Returns the elements of array «a» joined together into a single text value over index «i». If elements of «a» are numeric, [[JoinText]]() first converts them to text using the number format settings for the variable whose definition contains this function call. For example:

:<code>I := ['A', 'B', 'C']</code>
:<code>JoinText(I, I) → 'ABC'</code>
:<code>A := Array(I, ['VW', 'Honda', 'BMW'])</code>
:<code>B := Array(I, ['VW', Null, 'BMW'])</code>
:<code>JoinText(A, I) → 'VWHondaBMW'</code>

If the optional parameter «separator» is specified, it is inserted as a separator between successive elements, for example:

:<code>JoinText(A, I, ', ') → 'VW, Honda, BMW'</code>

The optional parameter «finalSeparator», if present, specifies a different separator between the second-to-last and last elements of «a».

:<code>JoinText(A, I, '; ', '; and') → 'VW; Honda; and BMW'</code>

Null values in «a» are ignored unless the optional parameter «textForNull» is specified.

:<code>JoinText(B, I, ', ') → 'one, two'</code>
:<code>JoinText(B, I, ', ', textForNull: '') → 'one, , two'</code>
:<code>JoinText(B, I, ', ' , textForNull: 'NULL') → 'one, NULL, two'</code>

The optional «default» parameter is returned when all values are ignored, or «a» has a zero length.

:<code>JoinText([Null, Null, Null], default: Null) → «null»</code>

==SplitText(text, separator, ''caseInsensitive, re'')==
Returns a list of text values formed by splitting the elements of text value text at each occurrence of separator «separator». For example:

:<code>SplitText('VW, Honda, BMW', ', ') → ['VW', 'Honda', 'BMW']</code>

[[SplitText]]() is the inverse of [[JoinText]](), if you use the same separators. For example:

:<code>Var x := SplitText('Humpty Dumpty sat on a wall.', ' ') → ['Humpty', 'Dumpty', 'sat', 'on', 'a', 'wall.']</code>
:<code>JoinText(x, , ' ') → 'Humpty Dumpty sat on a wall.'</code>

When «separator» contains letters, setting «caseInsensitive» to <code>True</code> matches in a lower/uppercase-insensitive manner. When the «re» parameter is <code>True</code>, separator is interpreted as a Perl-compatible [[regular expression]].

:<code>Variable s := 'Yes, Virginia. There is a Santa Claus!'</code>
:<code>SplitText(s, '[\s, \.!]+', re: 1) → ['Yes', 'Virginia', 'There', 'is', 'a', 'Santa', 'Claus', '']</code>
:<code>SplitText(TextTrim(s, trimChars: ' , .!'), '[\s, \.!]+', re:1) → ['Yes', 'Virginia', 'There', 'is', 'a', 'Santa', 'Claus']</code>

<tip title="Tip> With [[SplitText]](), «text» must be a single text value, not an array. Otherwise, it might generate an array of arrays of different length. See [[Ensuring Array Abstraction|Functions expecting atomic parameters]] on what to do if you want apply it to an array.
</Tip>

==TextLowerCase(t)==
[[TextLowerCase]]() returns the text «t» with all letters as lowercase. For example:

:<code>TextLowerCase('What does XML mean?') → 'what does xml mean?'</code>

==TextUpperCase(t)==
[[TextUpperCase]]() returns the text «t» with all letters as uppercase. For example:

:<code>TextUpperCase('What does XML mean?') → 'WHAT DOES XML MEAN?'</code>

==TextSentenceCase(Text, ''preserveUC'')==
[[TextSentenceCase]]() returns the text «t» with the first character (if a letter) as uppercase, and any other letters as lowercase. For example:

:<code>TextSentenceCase('mary ann FRED Maylene') → 'Mary ann fred maylene'</code>
:<code>TextSentenceCase(SplitText('mary ann FRED Maylene', ' ')) → ['Mary', 'Ann', 'Fred', 'Maylene']</code>
:<code>TextSentenceCase('they are Fred and Maylene', true) → 'They are Fred and Maylene'</code>

==NumberToText(x, format)==

NumberToText() converts number «x» to text using the specified «format». It provides all the settings and options available in the [[Number formats]] dialog for displaying a number (including a date number).

Possible values for «format» are: <code>'Suffix', 'Exponential', 'Fixed Point', 'Integer', 'Percent', 'Date', 'Boolean'</code>, or <code>'Hexadecimal'</code>. You can just use the first letter of a format to keep it brief:

:<code>NumberToText(3.45M, ['S', 'E', 'F', 'I', 'H']) → ['3.45M', '3.45.e+006', '3450000', '3450000', '0x34a490']</code>
:<code>NumberToText(0.0012, ['S', 'E', 'F', 'P']) → ['1.2m', '1.2e-003', '0', 0.12%']</code>

NumberToText() offers these optional parameters:

*«digits» specifies the precision for Suffix and Exponential formats, and the digits to the right of the decimal for Fixed Point and Percent formats, for example:

:<code>NumberToText(Pi, 'Suffix', digits: 5) → '3.1416'</code>
:<code>NumberToText(Pi, 'Fixed Point', digits: 5) → '3.14159'</code>
:<code>NumberToText(Pi, 'Percent', digits: 5) → '314.15927%'</code>

* «showZeros» forces the inclusion of trailing zeros:

:<code>NumberToText(1/4, 'Percent', digits: 2, showZeros: True) → '25.00%'</code>

Set «thousandsSeparators» to <code>True</code> to separate digits into groups of three:

:<code>NumberToText(7^12,'I', thousandsSeparators: True) → '13,841, 287, 201'</code>

* «currency» specifies a template with the currency symbol and its placement relative to the number and the minus sign.

:<code>NumberToText(-372, 'F', currency: ['-£#', 'US$-#', '#£-', '($#)']) → ['-£372', 'US$-372', '372£-', '($372)']</code>

* «dateFormat» provides a date format template for converting [[date numbers]] to text:

:<code>NumberToText(Today(), dateFormat: 'yyyy MMMM dd (wwww)') → '2013 July 01 (Monday)'</code>

* «fullPrecision»: Set this to true, to include all digits to ensure that the full precision of the number.

:<code>NumberToText(Pi, fullPrecision: True) → '3.141592653589793'</code>

== ParseNumber(text, ''badVal'') ==

Parses a text value into a number. (For dates, use [[ParseDate]]()). The result is independent of the number format setting. Values that are already numeric are returned. If the number is unparseable, it returns <code>Null</code>, unless you specify a different value to the optional parameter «badVal».

:<code>ParseNumber('12.43K') → 12.43K</code>
:<code>ParseNumber('hello') → «null»</code>
:<code>ParseNumber(14.3) → 14.3</code>

If you use <code>ParseNumber(x, x)</code> it will simply return any unparseable text values in «x» as the original text value:

:<code>VAR x := ['3, 214', 14, 'foo'] DO ParseNumber(x, x) → [ 3214, 14, 'foo']</code>

==TextCharacterEncode(type,text)==
(''New to [[Analytica 5.0]]'' ) Transforms «text» into an alternative text encoding specified by «type». The text can be ''URL encoded'' for inclusion in a URL or ''URL decoded'', ''XML encoded'', put into one of the four normalized unicode forms, or converted to or from a UTF-8 encoding. See [[TextCharacterEncode]].
:<code>TextCharacterEncode('UTF-8', 'γσh') → 'Î³Ïh'</code>
:<code>TextCharacterDecode('-UTF-8','Î³Ïh') → 'γσh'</code>
:<code>TextCharacterEncode('URL','3:4 = 3/4 & 1/2 = 0.5') → '3%3A4+%3D+3%2F4+%26+1%2F2+%3D+0.5'</code>

== TextDistance(t1,t2) ==
(''New to [[Analytica 5.0]]'' ) Returns a distance measure indicating how different two text values are. The result is the number of edit steps (substitutions, deletions, insertions, etc.) are required to transform «t1» into «t2». Many optional parameters can be used to specify which editing operations are allowed (see [[TextDistance]]()), allowing various standard distance measures including Levenshtein distance, Demerau-Levenshtein distance, Hamming distance, and Longest common subsequence among others.

:<code>[[TextDistance]]("portland", "orlando") → 3</code>
::Note: <code>"portland" → "ortland" → "orland" → "orlando"</code>

== Data file parsing and creation functions ==
When you exchange data with other applications (which in generally requires the [[Analytica Enterprise]] edition or better), you may need to parse the data, or put your data into a given format. Commonly used formats include CSV (which stands for Comma Separated Values, but includes other separators such as tabs), XML and JSON. The following functions can be used to parse or create data in these formats:
* [[ParseCSV]] and [[MakeCSV]]
* [[ParseJSON]] and [[MakeJSON]]
* The Microsoft XML DOM parser. See [[Example_Models#Extracting_Data_from_an_XML_file|Parsing an XML file]]. This uses [[COM Integration]] and requires the [[Analytica Enterprise]] edition.

:<code>[[ParseCSV]]( [[ReadTextFile]]( "MyData.csv" ) )</code> → { 2-D array indexed by local indexes <code>.Column</code> and <code>.Row</code>}

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Regular Expressions]]
* [[Asc]]()
* [[Chr]]()
* [[TextLength]]()
* [[SelectText]]()
* [[ FindInText]]()
* [[TextTrim]]()
* [[TextReplace]]()
* [[Text Concatenation Operator: &]]
* [[JoinText]]()
* [[SplitText]]()
* [[TextLowerCase]]()
* [[TextUpperCase]]()
* [[TextSentenceCase]]()
* [[NumberToText]]()
* [[TextDistance]]()
* [[TextCharacterEncode]]()
* [[Numbers and text]]
* [[Converting Numbers to Text]]
* [[ParseNumber]]()
* [[Model File Character Encoding]]
* [[Read and write text files]]
* [[Files and Editing]]
* [[Multiple formats in one table]]

</div>

<footer>Text, Date, Math, and Financial Functions / {{PAGENAME}} / Date functions</footer>

Error Messages/20394

2021-12-10T03:32:03Z

Fredbrunt: /* Description */

[[Category:Error messages]]

== Error messages ==

:<code>''OLE Linking is not available in the Analytica Free 101 edition.''</code>

:<code> ''If you would like to purchase Analytica Professional, which includes support for OLE linking, click the [http://www.lumina.com/shoppingcart/productorder/ Buy Analytica] link below.''</code>

:<code>''This file contains OLE links to external data. OLE linking is not available in Analytica Free edition, so these links cannot be refreshed. OLE linking is available in Analytica Professional and Analytica Enterprise. Click on the [http://www.lumina.com/shoppingcart/productorder/ Buy Analytica] link below to upgrade.''</code>

== Description ==

[[OLE Linking| OLE linking]] allows you to create a live link between to or from data outside Analytica. It is a lot like copy/pasting data, but in such a way that if the data changes, it is automatically refreshed.

OLE linking is a feature that is available in all paid-for editions of Analytica (Analytica Professional, Enterprise and Optimizer). It is not available in the Free edition.

== See Also ==
* [http://www.lumina.com/shoppingcart/productorder/ Buy Analytica]
* [[OLE linking]]
* [[Analytica User Guide]]

Error Messages/20394

2021-12-10T03:31:30Z

Fredbrunt: /* Error messages */

[[Category:Error messages]]

== Error messages ==

:<code>''OLE Linking is not available in the Analytica Free 101 edition.''</code>

:<code> ''If you would like to purchase Analytica Professional, which includes support for OLE linking, click the [http://www.lumina.com/shoppingcart/productorder/ Buy Analytica] link below.''</code>

:<code>''This file contains OLE links to external data. OLE linking is not available in Analytica Free edition, so these links cannot be refreshed. OLE linking is available in Analytica Professional and Analytica Enterprise. Click on the [http://www.lumina.com/shoppingcart/productorder/ Buy Analytica] link below to upgrade.''</code>

== Description ==

[[OLE Linking| OLE linking]] allows you to create a live link between to or from data outside Analytica. It is a lot like copy/pasting data, but in such a way that if the data changes, it is automatically refreshed.

OLE linking is a feature that is available in all paid-for editions of Analytica (Analytica Professional, Enterprise and Optimizer). It is not available in the Free 101 edition.

== See Also ==
* [http://www.lumina.com/shoppingcart/productorder/ Buy Analytica]
* [[OLE linking]]
* [[Analytica User Guide]]

ACP Style Library

2021-11-15T09:57:23Z

Fredbrunt: /* How to install the ACP Style library */ minor tweak to link

[[Category: Analytica Cloud Player]]
{{ReleaseBar}}

The [[Analytica Cloud Platform]] (ACP) offers a variety of user-interface styles and features useful for web applications, and not available in desktop Analytica. These include navigation styles with tabs across the top or down the left side, node styles, and Frame nodes to show tables and graphs embedded in a Diagram. Using the '''ACP Style Library''' makes it much easier to select these styles than setting special flags and codes in the [[AcpStyles]] attributes of the model. You should first import this library into desktop Analytica. {{Release||5.4| You can then select options in the library in desktop Analytica which shows previews of their effects in ACP.

You can see a video of the ACP Style library in use in the [https://youtu.be/OH3mYa_m0xE Analytica Cloud Player (ACP) Webinar]. }}

{{Release||6.0| After uploading the model into ACP, you can open the library and select styles. You will see their effects immediately in the ACP model. }}

=== How to install the ACP Style library ===

The ACP Style library is included as a standard Analytica library, but we recommend using '''the most recent ACP Style library version which you can download here: [[Media:ACP_style_library.ana|ACP style library.ana]],''' since there have been major enhancements recently.'''



After downloading the library into a folder, you can read it into your model:
# Make sure you are in edit mode.
# Click [[File menu]] > '''Add Module...'''
# Select '''ACP Styles.ANA''' from the folder into which you saved the file and click '''Open''
The 'ACP Styles library' will appear in the diagram:

{{Release||5.4|:[[File:Add styles library01.PNG]]}}
{{Release|6.0||:[[File:Reading ACP Style library into a model in desktop Analytica.png]]}}

{{Release|6.0||
=== Upload your model into ACP ===

Once you've imported the ACP Styles library into your model, you can use it to set ACP styles in desktop Analytica.
But, it's better to do in in ACP so you can immediately see the effects of each setting.

If you have an ACP account, you can upload your model into ACP from inside Analytica on the desktop:
* From the '''File''' menu, select '''Publish to cloud..'''

Otherwise, you can upload your model from inside ACP"
# Start up ACP from [https://acp.analytica.com/]
# Sign in (or sign up if you don't yet have an ACP account).
# When you see the '''Models''' tab, click the '''Upload''' button.
# Follow the file browser prompts to upload your model into ACP
# Click the name of your uploaded model to start it up in ACP.

=== How to set ACP styles ===

The easiest way to see what each option does is just to select from the menu or (uncheck) the checkbox. ACP will immediately show the effect of the changed style. The Default styles for tables and graphs show in the "Preview result" just to the right. A few, like the "Fly-in" option for Index menus show the Pivot icon only when you move your cursor over the "Preview result".

[[File:ACP Style library w Preview result styles.png|border]]

You can also move your cursor over each control to see its description in a balloon, in the usual way.

More details coming soon....

}}

{{Release||5.4|

=== How to use the ACP Style library ===

After installing the library into your model, double-click the '''ACP Style library''' node to view its main control panel:

:[[File:Open Styles Library01.png]]

Click one of these buttons to open a dialog to select those styles and options:
* [[#Navigation styles]]: For tab styles, expandable module outline, window size, and other options to navigate the model in ACP.
* [[#Node styles]]:For styles to display nodes, balloon help.
* [[#Frame nodes]]: To select text nodes that display edit and result tables and graphs embedded in a user-interface diagram.
See below for details on each dialog.

=== Set ACP styles in Analytica, and view them in ACP ===
You use the '''ACP Style library''' to set styles in Analytica on the desktop, but you can only see their effect in ACP. (The ACP Style library does show some examples of what the styles look like.) After setting some ACP styles, you can see their full effect by uploading your model into ACP. You can do this quickly by selecting '''Publish to cloud...''' from the '''File''' menu. It lets you upload and run the model in your free individual ACP account, or in an [[ACP Group Accounts|ACP Group account]] if you have one.

The library is invisible in ACP. Once you have selected the ACP styles you want, you can delete the ACP Styles Library from your model. Your selections model will remain. Tthe library file size is over 1 MB, so removing it from your model saves a little time when uploading and running the model in ACP.

==Navigation styles==

This dialog lets you configure the navigation style using the outline view, hierarchy header as in Analytica, or tabs across the top or down the left. You can also control the display of some elements such as those in the banner shown above the diagram. Click the '''Navigation styles''' button to get started.

[[File:NavStyleButton01.png]]

The Navigation styles dialogue window opens...

:[[File:Navstyle pane01.png]]

The '''Navigation style''' pulldown menu selects ways to navigate the model: The '''Preview''' pane beneath the menus shows an example ACP interface with the options you have selected:
:[[File:Navstyle01.png]]

The '''Navigation style''' options are:

* '''Outline''': With an expandable module hierarchy (see example below) that lets you quickly find the module you want to see, similar to the [[Outline window]] in Analytica on the desktop.
:[[File:Outline01.png]]

* '''Top diagram only''': Shows in ACP as a single diagram, with no Outline or hierarchy or tabs. This is useful when creating a simple Web application with a single UI, and no need for any navigation. Prevents opening other diagrams with the [[AcpStyles#Top Diagram Only]]. flag You need to arrange, and size the diagram to display what you want users to see in ACP.

'''Tabbed Navigation''' styles: These show the main modules in your top model as tabs (ordered left to right then top to bottom). It is most useful for creating a web application for people not familiar with Analytica. It works best when you create a few modules at the top level with user inputs and outputs, showing input tables and result tables and charts in [[#Frame nodes]]. The Navigation style menu offers these options:

'''Single level tabs''':

* '''Top tabs''': Display the tabs left to right across the top of the diagram. For example:

:[[File:ACP Tabs across top01.png]]

* Side tabs: Display the tabs in a column on the left of the diagram. For example:

:[[File:ACP Tabs down left01.png]]

'''Two-level hierarchical tabs''' : Modules in the main model appear as top tabs (left tabs). Modules in those top level modules appear as subtabs. When you select a top-level tab, it shows its submodules as subtabs.

*Two top tabs
*Two side tabs

'''Other Navigation Options''' In the top pane of the Navigation style dialog:

''These next two checkboxes are unusable - and so are hidden - when you have not selected a tabbed Navigation style.''

*'''Include top level diagram as tab:''' Can be used only with 'Side tabs' or 'Top tabs'. You may check this checkbox to include the top model diagram as the leftmost tab for "Side tabs", or top tab for "Top tabs". If you uncheck this checkbox, the top diagram will not display in ACP, so you include the key user interface pages as modules in the main model. Currently for 2 level tabs it is required to exclude the top diagram from the tabs, so this checkbox is hidden. [[AcpStyles#Exclude_the_top_level_diagram_from_tabs| More...]]

:[[File:Show as tab01.png]]

*'''Show hierarchy''': Lists the titles of the top, ancestor, parent, and current modules to show where you are in a model (see example below). You can click any ancestor to move up the module hierarchy, similar to the [[Show module hierarchy]] in Analytica on the desktop. Note that, to save screen space, the hierarchy does not display when it would be redundant, showing the same information displayed on the top tabs or side tabs, i.e. in the top levels of the model. The Show Hierarchy style is controlled by a checkbox in the Edit menu's preferences dialog in Desktop Analytica. Both the Hierarchy and the outline tree will show if this preference is checked, but the Styles library will turn this preference off if you select '''Outline''' style, since it duplicates the information on the outline. For the '''Top diagram only''' style there is no need for the hierarchy.
:[[File:Show hierarchy01.png]]

*'''Minimum resolution''': The resolution in pixels of the smallest screen that your end users may have. ACP uses a fixed browser window size (canvas) for all Diagrams (tabs), unlike Analytica on the desktop that lets you have a different window size for each one. It's important to select a size that works well for all users, even on laptops with smaller screens. When you select a minimum resolution for the screen, it automatically resizes the main Diagram size in the desktop so that it will work well in ACP. The actual diagram size will be smaller than the screen resolution to allow for space for the web browser controls, menus, and tabs at the top, and window edges and scroll bars that take a little space on the sides and bottom.

:[[ACP_Diagram_Sizes#Diagram_Size_in_the_ACP_Style_Library|More...]]<br/>
:[[File:Min res01.png]]

===ACP Navigation options===

In this bottom section of the ACP Navigation styles, you can control how the banner area above your diagram appears and whether or not to add scroll bars. To simplify the process of setting the styles, these checkboxes are hidden if you have selected an incompatible Navigation style in the top pane.

:[[File:Navigation checkboxes01.png]]
====Banner logo and tabs====
Unchecking the 'Banner logo and tabs' hides the banner space usually present at the top of ACP. The banner typically contains the Lumina Logo, the '''Parent Diagram''' button, tabs, '''Close Model''' button, and '''Save''' button.

:[[File:Styles library 16.png]]

====Parent button====
Flag to control the display of the '''Go into Parent''' button. Currently the button is shown by default with Outline style. The checkbox is hidden in other styles. It is possible to display this button with top tabs, but not by using the styles library, since there are some model specific settings involved. [[AcpStyles#Go_into_Parent_Button Not compatible with Side tabs. | More...]]

:[[File:Styles library 17.png]]

====Toolbar tabs====

By clearing this checkbox, you can remove the default ACP tabs that appear at the top of ACP. These are the tabs with titles like "Diagram", "Object", "Edit Table", "Table", "Graph"... Toolbar tabs are compatible only with 'Outline' style. They will not show if the model title is shown, since they would tend to overlap.

:[[File:Styles library 18.png]]

====Use Top diagram size for all windows====
Sets the size of all diagrams based on the size of the diagram window of the top level when the model was last viewed in Desktop Analytica (in non-maximized mode). This is mandatory in all but 'Outline' style.

====Model title====
Shows the title of the model at the top to the right of the Lumina (or other) logo. Note that if you check this the toolbar tabs will not show, because the tabs and title would overlap,

:[[file:Styles library 19.png]]

===Diagram title===
You can control whether or not to display the diagram's title at the top of the diagram. Only usable with 'Outline' style. (And the preference for showing the model hierarchy needs to be turned off as explained above, ).

:[[file:styles library 20.png]]

====Auto calc====
Checking this causes ACP to calculate any result (table or graph) as it displays a diagram window containing the result, and to immediately recalculate any result when the user changes an input on that diagram that affects the result. (It combines Calculate on open and Auto recalc results.) This behavior is unlike Analytica which does not usually calculate results until the user asks for them by clicking the Calc button.

====Add Scroll bars====
When checked, ACP adds scroll bars if needed to be able to see the entire diagram. When unchecked, the diagram will be either the top diagram size if this flag is set, or the canvas size.

'''Once you have the navigation styles set the way you want, click '''Close'''. This will close the Navigation panel and take you back to the Main ACP Style Library diagram. '''

:[[File:CloseNavstyles01.png]]

==Node styles==

The Node styles dialog lets you configure how nodes are displayed including bevels and shadows. You can specify the style for highlighting when you move the mouse over a node, and whether to show [[Help balloons|balloon help]] with a description for each node.

:[[File:Nodestyledialog01.png]]

===Node effect on mouse-over===
Select a highlighting effect for nodes when you move the cursor over the node. The default setting is 'Outline', with 'Glow' and 'None' as the other choices. As you select an effect from the pulldown menu a preview is shown.

:[[File:ACP Effect on mouseover01.PNG]]

===Node edge appearance===
In this pane, the 2 checkboxes set flags controlling the appearance of the edge of the nodes. Bevels adds a 3 d bevel to the node. Shadows adds a drop shadow effect. You can select either of these effects or both.

:[[File:ACP Node edge appearance01.PNG]]

===Balloon help===
This pane has two checkboxes to set whether the identifier and/or the definition is also shown in the [[Help balloons|balloon]], and a pulldown menu which sets the delay before a balloon appears.

By default, ACP displays the description - if any - the units, and the title of an object in a balloon as you place the mouse over it. If there is no description the balloon will not appear.

:[[File:Default Balloon wiki071212.PNG]]

'''Identifier in balloon.''' This can be useful when a node is titled 'Net present value' and has an identifier <code>Npv</code> for example.

:[[File:Id in balloon wiki071212.PNG]]

'''Definition in balloon.''' When checked, it shows the Definition of a variable in the balloon when you move the mouse cursor over its node.

:[[File:Def in Balloon wiki071212.PNG]]

'''Both Definition and Identifier boxes checked'''

:[[File:Def id in balloon wiki071212.PNG]]

'''Balloon delay''' When you mouse over a node, there's a short delay of about half a second before it displays the balloon (to prevent wild balloon appearance when you move the cursor rapidly over a diagram.) You can tweak this delay time measured in seconds.

:[[File:Balloon delay wiki 071212.PNG]]

===Uncertainty icon in outputs===
Analytica normally shows, just to the right of an output node, a little icon indicating the uncertainty view last displayed e.g. [[mid]], [[mean]], [[ProbBands]], [[pdf]] ...

You can suppress these icons. This might be desirable, for instance, if your model is not probabilistic.

:[[file:styles library 27.png]]

===Flash buttons===
For button nodes, instead of drawing a button that looks like a button node in desktop Analytica, use a Flash button. A Flash button component looks and feels a little bit more like a GUI button used in software applications.

If you are building a web application which uses '''Submit''' or other buttons, you might find it looks better using the Flash button component rather than a traditional Analytica button node.

However, if you are using multi-line text or have images embedded in any of the button nodes, then you should not use Flash Buttons since they don't support these features.

:[[File:Styles library 28.png]]

'''*Once you have the Node styles set remember to click 'done'. This will apply the node style attributes you have selected to the model and return you to the ACP Style Library diagram'''

:[[File:Nodestyleclose01.png]]

==Frame nodes==

:[[File:Styles library 05.png]]

:[[File:Styles library 08.png]]

'''What is a frame node?'''
If you are creating a Web Application which does not use the toolbar tabs, then you probably will want to display tables and graphs on the influence diagram. You can specify the location and size of the tables and graphs on the diagram using a Frame node. A module frame node is just a text node in a module that one tells ACP to use as the location for displaying tables and graphs in that module.

These are used with Web Application navigation styles where the toolbar tabs are not present. If you are not using one of the Web Application navigation styles, then you can skip this step.

'''How to make a text node be a frame node'''

First, create a text node in the module you want to display tables and graphs. Here is a Model with a text node on the top diagram.

:[[file:Styles library 30.png]]

===Select frame===

*In the Frame Nodes control panel, select the module where the text node is located from the 'Select module' pulldown menu.

*Select the frame node's identifier from the 'Select frame node' pulldown menu.
''(If the text node is newly added to the model, it may not be listed if this variable has not been 'dirtied'. If it is not listed, you need to click the refresh button.)''

:[[File:Styles library 29.png]]

*Once you have the correct node selected, then check "Use as a module frame node".

:[[File:Use as frame node 071212.PNG]]

Once you check this checkbox the options in the field below will be displayed and enabled..

:[[File:Set Frame node01 071212.PNG]]

===Select frame node styles===

'''Index Menus''' Controls the display of the Index pulldown menus on the diagram. Unchecked by default, since this saves diagram space, and it is assumed that a modeller will usually choose how he wants people to view the orientation and dimensions of a table/graph in his model on the web. If you want people to be able to view and use these menus in ACP, check this box.

:[[File:Index menu no 0071212.PNG]][[File:Index menu yes 0071212.PNG]]

'''Title''' This checkbox controls whether or not the title of the node is shown above the table or graph on the diagram.

'''Description''' This checkbox controls whether or not the description of the node is shown above the table or graph on the diagram.

'''Description length''' Length of description of variable as a percent of Frame height. Not enabled if the 'description' check box is unchecked. If the Description is too long to fit the allotted space, it will be truncated and a scroll bar will be used to view the entire description. (This feature will only display correctly if you have made the frame node large enough to accommodate the scroll bar within the allotted space).

:[[File:Descr 50 071212.PNG]]

'''Table and or graph''' When the results of a node are shown, you have the following options, to show just the graph, just the table, show both the table and the graph. If you want the table or graph to be shown based on what was viewed last in Analytica, you can choose 'As saved in Analytica'.

For edit tables, the table will always be displayed regardless of this setting.

:[[File:Table over graph 071212.PNG]]

Once you have chosen the settings for your frame node, you can make another frame node, either in a different module or in the same module. If there is more than one Frame, each time you click on a node, it will show its table or graph in the Frame whose contents was displayed the longest ago. Thus, as you click on different nodes, it cycles through the Frames. In this way, you can see and compare edit tables or results from multiple nodes -- all in the same diagram window.

Click '''Done''' when your settings are complete.
}}

==See Also==
* [[Media:ACP style library.ana|ACP style library.ana]]
* [[AcpStyles]]
{{Release||5.4| * [https://youtu.be/OH3mYa_m0xE Analytica Cloud Player (ACP) Webinar] }}
* [[Analytica Cloud Platform]]

Formatted Text Literals

2021-04-03T07:51:22Z

Fredbrunt: /* Width and Alignment */ fix typo in expression

''New to [[Analytica 6.0]]''

A [[Formatted Text Literals|formatted text literal]] (or F-string for short) is a double-quoted text literal that is prefixed with an F or f. These can include replacement expressions that are delineated by curly braces, which get replaced by the result of evaluating the expressions.

The following is an example of an F-String that inserts the current values of x, y and x+y:
:<code>F"The value of x is {x}, y is {y} and their sum is {x+y}"</code>

Although you could accomplish the same result using [[Text_Concatenation_Operator%3A_%26|text-concatenation]] as
:<code>"The value of x is " & x & ", y is " & y & " and their sum is " & (x+y)</code>
the version using F-strings is more concise and easier to read.

[[Formatted Text Literals]] aren't really literals like normal single- or double-quoted text values are. They are instead themselves expressions whose value is determined at evaluation time. Nevertheless, because they have the syntactic appearance of literals, the term is used. The names [[Formatted Text Literals]] and [[F-Strings]] are borrowed from [https://docs.python.org/3/reference/lexical_analysis.html?highlight=formatting#formatted-string-literals Python].

== Syntax ==

A [[Formatted Text Literals|formatted text literal]] starts with either <code>F"</code> or <code>f"</code>, and ends with <code>"</code>. In other words, it is a double-quoted text value prefixed with an upper or lower case F. There can be no space between the F and the opening quote. Within the text, expressions are inserted using curly braces, <code>{expr}</code>. When the F-String is evaluated, the expressions in curly braces are evaluated and their result is substituted for the curly braces and expression.

There is currently no single-quoted version of F-strings in Analytica, so you cannot write <code>f'Something'</code>. It must use double quotes is in <code>f"Something"</code>.

If you want to embed a double quote (<code>"</code>), or curly brace (<code>{</code> or <code>}</code>) in the text part of an F-string, you must double the character. For example,
<pre>
F"An F-string has the form F""some text {{ an expression : format spec }} some more text""."
</pre>
which has the content: ''An F-string has the form F"some text { an expression : format spec } some more text".''

When the curly braces are not doubled, the content between them is parsed as an expression. Optionally, the expression can be followed by a colon (<code>:</code>) and a [[#Format Specifiers|format specifier]]. For example:
:<code>F"1/3 = {1/3 : %6}"</code> → "1/3 = 33.333333%"

When you omit a format specifier, the [[Number formats|number format]] for the current expression context is used, i.e., for the current variable or [[User-Defined Function]], which you set using the [[Number formats|number format dialog]].

== Array abstraction ==
When your expression evaluates to an array, a separate text value is created for each cell. When you have more than one expression, the indexes of your final result will be the union of the indexes for all the expressions. For example:<code>
:[[LocalIndex]] X := 1..9;
:[[LocalIndex]] Y := 1..9;
:F"{X} * {Y} = {X*Y}"
</code>
returns a 2-D array having 81 cells:
<center>[[image:FstringExampleXxY.png]]</center>

A format specifier is static. It isn't computed and cannot vary along any index, so the same format specifier (if any) applies to every cell of the result.

== Format Specifiers ==
Format specifiers are optional, but when you want to specify the format, follow your expression with a colon and then with the format specifiers. F-String format specifiers are terse by design, so as to minimize the distraction from the content and keep your formatted text literal looking as much as possible like the final result. But being terse, they are also cryptic. Except for numeric parts, each element of the format is denoted by a single character. Analytica's format specifiers have several similarities to Pythons, but are not exactly the same.

You don't need a format specifier when you've set the [[Number formats|Number Format]] of your variable or [[UDF]] to be as you'd like. Also, you have the option of using [[NumberToText]] for a more descriptive way to specify the format.

A format specifier can specify the following information:
* The number format for numeric values
* Minimum width (in characters) and alignment within that space
* The date template for date-time values
All three are optional, or you may specify more than one.

Parts that aren't explicitly specified are inherited from the current variable or [[UDF]]'s number format.

=== Number formats ===
A number format type can be one of the following characters:
* <code>S</code> or <code>s</code>: Suffix
* <code>E</code> or <code>e</code>: Exponential
* <code>G</code> or <code>g</code>: General
* <code>F</code> or <code>f</code>: Fixed point
* <code>I</code> or <code>i</code>: Integer
* <code>P</code>, <code>p</code> or <code>%</code>: Percent
* <code>B</code>: Boolean (Prints as True or False)
* <code>H</code>, <code>h</code>, <code>X</code> or <code>x</code>: Hexadecimal
* <code>b</code>: binary

The type can be followed by the number of digits or decimals, such as <code>G12</code> for General type with 12 digits. For suffix, exponential, general, hex and binary types, the number is the number of digits total, for fixed point and percent types it is the number of decimal places. See [[Number formats]].

The following characters specify additional components of the number format:
* <code>'!'</code>: Display full precision
* <code>0</code> or <code>z</code>: Show trailing zeros. If you use 0, it needs be separated in some way from the number of digits, such as by a space of '.'. E.g., F10 is Fixed point with 10 decimals, whereas F1.0 is fixed point with 1 decimal and trailing zeros.
* <code>,</code>: Show thousands separators
* ''space'' or <code>.</code>: Ignored characters.

A few options not available (if you need these, use [[NumberToText]]) are: Currency symbols, use of parentheses for negative numbers, control of the ordering of currency, sign and digits.

Examples:
:<code>F"π={Pi:!}"</code> → "π=3.141592653589793"
:<code>F"The 25th power of 3 is {3^25:I,}"</code> → "The 25th power of 3 is 847,288,609,443"
:<code>F"${profit:F2,0}"</code> → "$17,343,300.00"

=== Width and Alignment ===
When you specify a (minimum) width and alignment, the expression uses at least that number of characters, using spaces to pad unused space. The alignment character comes first, followed by the width, and both are required. The possible alignment characters are:
* <code>L</code> or <code><</code>: Left align
* <code>R</code> or <code>></code>: Right align
* <code>C</code> or <code>^</code>: Center align

Examples:
:<code>F"π≈{pi:R10G4} π/2≈{pi:L10G4} |π^2≈{pi:C10G4}|"</code> → "π≈ 3.142 π/2≈1.571 |π^2≈ 9.87 |"
:<code>F"Cost=${Cost:I,R15}"</code>→[[image:FStringCurrencyLeft.png]]
:<code>F"Cost={F"${Cost:I,}":R15}"</code> →[[image:FStringCurrencyWithNumber.png]]

The last example shows how you can use a nested F-string to produce a fixed-width cost column while keeping the $ attached to the number.

=== Date template ===
The date template is used to render date-time values. This can be specified along with a number format, so that when an expression returns an array of values with some dates and some numbers, the number format is used for numbers and the date format for dates.

The date template is preceded by the letter <code>D</code>, and then continues to the closing curly brace. The date format therefore must be last and come after any alignment and width or number format. Any spaces that appear after the D and before curly brace become part of the final text. The date template specified in an F-string cannot contain curly braces. Otherwise, it uses the same conventions as the date template in the number format dialog.

Example:
* <code>F"The current time is {Today(true):Dhh:mm:ss tt}"</code> → "The current time is 03:31:38 PM"
* <code>F"In the US it is {Today():DMM/dd/yyyy}, but in Europe it is {Today():Ddd/MM/yyyy}."</code> →
*:::"In the US it is 03/24/2021, but in Europe it is 24/03/2021."

== See Also ==

* [[Text_Concatenation_Operator%3A_%26|The text-concatenation operator, &]]
* [[NumberToText]]
* [[Number formats]]
* [[Text values]]
* [[JoinText]]