Analytica Docs - User contributions [en]

NumberToText

2012-07-04T21:00:38Z

LonnieTest:

''New to [[Analytica 4.5]]''

''Note: A preliminary version is included in patch release 4.4.3, but not exposed on menus or in the User Guide. The function included with 4.4 is subject to change.''

= NumberToText( x'', format, digits, showZeroes, separators, currency, dateFormat, fullPrecision'' ) =

Convert a number (or date-time number) to text with explicit control over the [[Number format|number format settings]]. The parameters are similar to those found on the [[Number Format Dialog]].

When «x» is a non-numeric value (text, [[Null]], [[Handle]]s, [[References]], etc., then the value of «x» is returned without modification.

Prior to the introduction of this function, you would need to [[Text Concatenation Operator: &|concatenate text to the number]], e.g., <code>"" & x</code>, during which the number format for the current object controls how the resulting number is formatted (see [[Converting Numbers to Text|coercing numbers to text]]). This remains a perfectly good way to coerce numbers to text, but [[NumberToText]] provides yet another option, with some new flexibility. If you are using a pre-4.5 release, you should continue to use the concatenation method.

=== Parameters ===

* «format»
*: The type of format used for numbers (but not date or date/time values). It can be one of the following values (or just the first letter):
** "Suffix" (39.63K)
** "Exponential" (3.963e+004)
** "Fixed Point" (39632.55)
** "Integer" (39633)
** "Percent" (3963254.89%)
** "Date" (4-Jul-2012) -- forces numbers to display as dates
** "Boolean" (True)
** "Hexadecimal" (0x9ad1)
* «digits»
*:The number of significant digits for Suffix and Exponential formats, or the number of digits to the right of the decimal point for Fixed Point and Percent formats.
* «showZeroes»
*: Boolean specifying whether to show training zeroes.
* «separators»
*: Boolean specifying whether to show separators. In the US, this would be commas between each group of three digits (e.g., 39,632.55).
* «currency»
*: Specifies the currency symbol to display, or the symbol and its placement relative to the digits and sign. The following placement templates recognized, where the <code>$</code> can be replaced by any currency symbol.
** "$-#"
** "$#-"
** "-$#"
** "-#$"
** "#$-"
** "#-$"
** "(#$)"
** "($#)"
** "regional"
* «dateFormat»
*: The template used to display dates, times, or date-time numbers. The following patterns are substituted, and anything else is printed literally.
** "SHORT", "ABBREV", "LONG", "TIME", "DATETIME": regional-specific standard formats.
** y, yy, yyyy: The year. y=two digit, no leading zero. yy=two digits. yyyy=four digits.
** M, MM: The month number, without or with leading zero.
** MMM, MMMM: The month name, abbreviated or full ("Jan" or "January")
** d, dd: The day number, without or with leading zero.
** w: The weekday number
** www, wwww: The weekday name, abbreviated or full ("Wed", or "Wednesday")
** q : The quarter (1 thru 4)
** h, hh: The numeric hour from 1 thru 12, without or with leading zero.
** tt : AM or PM
** H, HH: The numeric hour from 0 thru 23, without or with leading zero.
** m, mm: The numeric number of minutes, from 0 to 59, without or with leading zero.
** s, ss: The whole number portion of seconds, from 0 to 59, without or with leading zero.
** .ssssss: The fractional seconds (up to 6 digits)
** ' ''literal text'' ': The literal text is shown. If you want the ' character to show, then you must double it.
* «fullPrecision»
*: A boolean value. When set to true, the number is displayed at full precision even if this requires exceeding the number of digits specified in «digits».

= Examples =

<pre>
NumberToText( -1234567.89012, "Fixed Point", 1 ) → "-1234567.9"
NumberToText( -1234567.89012, digits:6 ) → "-1.23456M"
NumberToText( 0.8, "Percent", 4, showZeroes:true ) → "80.0000%"
NumberToText( -594321.342, "Fixed Point", separators:true, currency:"-# USD ) → "-594,321.34 USD"
NumberToText( -594321.342, "Fixed Point", separators:true, currency:"(€#)") → "(€594,321.34)"
NumberToText( 594321.342 "Fixed Point", separators:true, currency:"(€#)") → "€594,321.34"
NumberToText( 594321.342, "Fixed Point", separators:true, currency:"$-#") → "$594,321.34"
NumberToText( 594321.342, "Suffix", 3, currency:"£") → "£594K"
NumberToText( 4-Jul-2012 13:52:03, dateFormat:"www, MMMM dd, ''''yy 'at' hh:mm tt") → "Wed, July 04, '12 at 01:52 PM"
</pre>

= See Also =

* [[Converting Numbers to Text]]
* [[Function Parameter Qualifiers#Coerce|Coerce Function Parameter Qualifier]]
* [[ParseNumber]]
* [[ParseDate]]
* [[Number Format Dialog]]
* [[User-Defined Functions]]

NumberToText

2012-07-04T20:43:06Z

LonnieTest: mention of concatenation

''New to [[Analytica 4.5]]''

''Note: A preliminary version is included in patch release 4.4.3, but not exposed on menus or in the User Guide. The function included with 4.4 is subject to change.''

= NumberToText( x'', format, digits, showZeroes, thousandsSeparators, currency, dateFormat, fullPrecision'' ) =

Convert a number (or date-time number) to text with explicit control over the [[Number format|number format settings]]. The parameters are similar to those found on the [[Number Format Dialog]].

When «x» is a non-numeric value (text, [[Null]], [[Handle]]s, [[References]], etc., then the value of «x» is returned without modification.

Prior to the introduction of this function, you would need to [[Text Concatenation Operator: &|concatenate text to the number]], e.g., <code>"" & x</code>, during which the number format for the current object controls how the resulting number is formatted (see [[Converting Numbers to Text|coercing numbers to text]]). This remains a perfectly good way to coerce numbers to text, but [[NumberToText]] provides yet another option, with some new flexibility. If you are using a pre-4.5 release, you should continue to use the concatenation method.

=== Parameters ===

* «format»
*: The type of format used for numbers (but not date or date/time values). It can be one of the following values (or just the first letter):
** "Suffix" (39.63K)
** "Exponential" (3.963e+004)
** "Fixed Point" (39632.55)
** "Integer" (39633)
** "Percent" (3963254.89%)
** "Date" (4-Jul-2012) -- forces numbers to display as dates
** "Boolean" (True)
** "Hexadecimal" (0x9ad1)
* «digits»
*:The number of significant digits for Suffix and Exponential formats, or the number of digits to the right of the decimal point for Fixed Point and Percent formats.
* «showZeroes»
*: Boolean specifying whether to show training zeroes.
* «thousandsSeparators»
*: Boolean specifying whether to show separators. In the US, this would be commas between each group of three digits (e.g., 39,632.55).
* «currency»
*: Specifies the currency symbol to display, or the symbol and its placement relative to the digits and sign. The following placement templates recognized, where the <code>$</code> can be replaced by any currency symbol.
** "$-#"
** "$#-"
** "-$#"
** "-#$"
** "#$-"
** "#-$"
** "(#$)"
** "($#)"
** "regional"
* «dateFormat»
*: The template used to display dates, times, or date-time numbers. The following patterns are recognized.
** "SHORT", "ABBREV", "LONG", "TIME", "DATETIME": regional-specific standard formats.
** Y, YY, YYYY: The year. y=two digit, no leading zero. yy=two digits. yyyy=four digits.
** M, MM: The month number, without or with leading zero.
** MMM, MMMM: The month name, abbreviated or full ("Jan" or "January")
** D, DD: The day number, without or with leading zero.
** W: The weekday number
** WWW, WWWW: The weekday name, abbreviated or full ("Wed", or "Wednesday")
** q : The quarter (1 thru 4)
** h, hh: The numeric hour from 1 thru 12, without or with leading zero.
** tt : AM or PM
** H, HH: The numeric hour from 0 thru 23, without or with leading zero.
** m, mm: The numeric number of minutes, from 0 to 59, without or with leading zero.
** s, ss: The whole number portion of seconds, from 0 to 59, without or with leading zero.
** .ssssss: The fractional seconds (up to 6 digits)
* «fullPrecision»
*: A boolean value. When set to true, the number is displayed at full precision even if this requires exceeding the number of digits specified in «digits».

= See Also =

* [[Converting Numbers to Text]]
* [[Function Parameter Qualifiers#Coerce|Coerce Function Parameter Qualifier]]
* [[ParseNumber]]
* [[ParseDate]]
* [[Number Format Dialog]]
* [[User-Defined Functions]]

NumberToText

2012-07-04T20:33:35Z

LonnieTest: Created first revision

Number Format Dialog

2012-07-04T20:05:26Z

LonnieTest: Redirected page to Number format

#REDIRECT [[Number format]]

Alphabetical Function List

2012-07-04T19:48:51Z

LonnieTest:

[[Category:Functions]]
(Back to [[Analytica Reference]])

See also: [[:Category:Functions|functions by category]].

* [[Comparison Operators|=,<,>,<>,<=,>=]] : Comparison operators
* [[Subscript/Slice Operator| [I=x] ]] : Subscript operator
* [[Subscript/Slice Operator| [@I=x] ]] : Slice operator
* [[Using References|\]] : Reference operator
* [[Dereference Operator|#]] : Dereference operator
* [[Index Position Operator::@|@]] : Index Position operator
* [[Assignment Operator:: ::=|:=]] : Assignment operator
* [[Text Concatenation Operator: &|&]] : Text concatenation operator
* [[Dot operator::A.I|A.I]] : Dot operator, to access a local index of an array
* [[Abs]]
* [[Aggregate]]
* [[AnalyticaLicenseInfo]]
* [[And]]
* [[ArcCos]]
* [[ArcCosH]]
* [[ArcSin]]
* [[ArcSinH]]
* [[ArcTan]]
* [[ArcTan2]]
* [[ArcTanH]]
* [[Area]]
* [[ArgMin_and_ArgMax| Argmax]]
* [[ArgMin_and_ArgMax| Argmin]]
* [[Array]]
* [[Asc]]
* [[AskMsgChoice]]
* [[AskMsgNumber]]
* [[AskMsgText]]
* [[Assignment Operator:: ::=]] : Assignment operator
* [[AttribGet]]
* [[Average]]
* [[Bernoulli]]
* [[BesselJ]], [[BesselY]], [[BesselI]], [[BesselK]]
* [[Beta]]
* [[Beta_m_sd|Beta_m_sd]] (Distribution variations.ana)
* [[Betafn]]
* [[BetaI]]
* [[BetaIInv]]
* [[Binomial]]
* [[BiNormal]] (Multivariate distributions.ana)
* [[Boolean]]
* [[CAbs]] (Complex Library.ana)
* [[CAdjoint]] (Complex Library.ana)
* [[Calloption]] (Financial Library.ana)
* [[Capm]] (Financial Library.ana)
* [[CArcCos]] (Complex Library.ana)
* [[CArcSin]] (Complex Library.ana)
* [[CArcTan]] (Complex Library.ana)
* [[CCos]] (Complex Library.ana)
* [[CDeterminant]] (Complex Library.ana)
* [[Cdf]]
* [[CDiv]] (Complex Library.ana)
* [[Ceil]]
* [[Certain]]
* [[CExp]] (Complex Library.ana)
* [[ChanceDist]]
* [[Change_index]] (Expand Index.ana)
* [[ChiSquared]]
* [[Choice| Choice]]
* [[CInverse]] (Complex Library.ana)
* [[Chr]]
* [[CLn]] (Complex Library.ana)
* [[CMatMult]] (Complex Library.ana)
* [[CMult]] (Complex Library.ana)
* [[Coerce_to_Numeric]] (Flat file library.ana)
* [[Combinations]]
* [[Comparison Operators]]: =, <, >, <>, <=, >=
* [[Complex]] (Complex Library.ana)
* [[CompressMemoryUsedBy]]
* [[ComputedBy]]
* [[Concat]]
* [[ConcatN|Concat<N>]] (Concatenation UDFs.ana
* [[ConcatRows]] (Concatenation UDFs.ana)
* [[Functions_Min_and_Max| Condmax]]
* [[Functions_Min_and_Max| Condmin]]
* [[Continuous]]
* [[CopyIndex]]
* [[Correlate_Dists]] (Multivariate Distributions.ana)
* [[Correlate_With]] (Multivariate Distributions.ana)
* [[Correlation]]
* [[Trig Functions| Cos]]
* [[Trig Functions| Cosh]]
* [[CostCapme]] (Financial Library.ana)
* [[CostCapmm]] (Financial library.ana)
* [[CRoots]] (Complex Library.ana)
* [[CSin]] (Complex Library.ana)
* [[CSqrt]] (Complex Library.ana)
* [[CTan]] (Complex Library.ana)
* [[CTheta]] (Complex Library.ana)
* [[CToPolar]] (Complex Library.ana)
* [[CubicInterp]]
* [[CumBinomial]] ([[Distribution Densities Library]])
* [[CumChiSquared]] ([[Distribution Densities Library]])
* [[CumChiSquaredInv]] ([[Distribution Densities Library]])
* [[CumDist]]
* [[CumExponential]] ([[Distribution Densities Library]])
* [[CumExponentialInv]] ([[Distribution Densities Library]])
* [[CumFDist]] ([[Distribution Densities Library]])
* [[CumFDistInv]] ([[Distribution Densities Library]])
* [[CumIPmt]]
* [[CumLogistic]] ([[Distribution Densities Library]])
* [[CumLogisticInv]] ([[Distribution Densities Library]])
* [[CumLogNormal]] ([[Distribution Densities Library]])
* [[CumLogNormalInv]] ([[Distribution Densities Library]])
* [[CumNormal]]
* [[CumNormalInv]]
* [[CumPoisson]] ([[Distribution Densities Library]])
* [[CumPrinc]]
* [[CumProduct]]
* [[CumStudentT]] ([[Distribution Densities Library]])
* [[CumStudentTInv]] ([[Distribution Densities Library]])
* [[CumTriangular]] ([[Distribution Densities Library]])
* [[CumTriangularInv]] ([[Distribution Densities Library]])
* [[CumWilcoxon]]
* [[CumWilcoxonInv]]
* [[Cumulate]]
* [[CumUniform]] ([[Distribution Densities Library]])
* [[CumUniformInv]] ([[Distribution Densities Library]])
* [[CumWeibull]] ([[Distribution Densities Library]])
* [[CumWeibullInv]] ([[Distribution Densities Library]])
* [[CurrentDataDirectory]]
* [[CurrentModelDirector]]
* [[DateAdd]]
* [[DatePart]]
* [[DbLabels]]
* [[DbQuery]]
* [[DbTable]]
* [[DbTablenames]]
* [[DbWrite]]
* [[Decompose]]
* [[Degrees]]
* [[Dens_Beta]] ([[Distribution Densities Library]])
* [[Dens_ChiSquared]] ([[Distribution Densities Library]])
* [[Dens_CumDist]] ([[Distribution Densities Library]])
* [[Dens_Exponential]] ([[Distribution Densities Library]])
* [[Dens_FDist]] ([[Distribution Densities Library]])
* [[Dens_Gamma]] ([[Distribution Densities Library]])
* [[Dens_Gaussian]] ([[Distribution Densities Library]])
* [[Dens_Logistic]] ([[Distribution Densities Library]])
* [[Dens_LogNormal]] ([[Distribution Densities Library]])
* [[Dens_Normal]] ([[Distribution Densities Library]])
* [[Dens_ProbDist]] ([[Distribution Densities Library]])
* [[Dens_StudentT]] ([[Distribution Densities Library]])
* [[Dens_Triangular]] ([[Distribution Densities Library]])
* [[Dens_Uniform]] ([[Distribution Densities Library]])
* [[Dens_Weibull]] ([[Distribution Densities Library]])
* [[Dereference Operator::#|Dereference Operator: #R]] : Return the value pointed to by a reference R.
* [[Determinant]]
* [[DetermTable]]
* [[Dirichlet]] (Multivariate distributions.ana)
* [[Discrete]]
* [[Dispatch]]
* [[Dist_additive_growth]] (Multivariate distributions.ana)
* [[Dist_compound_growth]] (Multivariate distributions.ana)
* [[Dist_reshape]] (Multivariate distributions.ana)
* [[Dist_serial_correl]] (Multivariate distributions.ana)
* [[DomainAllowed]]
* [[DomainIntegerGroup]]
* [[DomainLowerBound]]
* [[DomainNullOk]]
* [[DomainType]]
* [[DomainUpperBound]]
* [[DotProduct]]
* [[Dydx]]
* [[Dynamic]]
* [[EigenDecomp]]
* [[Elasticity]]
* [[Erf]]
* [[ErfInv]]
* [[Erlang]] (Distribution variations.ana)
* [[Error]]
* [[Evaluate]]
* [[EvaluateScript]]
* [[Exp]]
* [[Exponential]]
* [[expr1 ; expr2]] : Expression Sequence Operator
* [[Factorial]]
* [[FindInText]]
* [[FindPolynomialZeroes]]
* [[Floor]]
* [[For..Do]]
* [[Fractiles]]
* [[Frequency]]
* [[FunctionOf]]
* [[Fv]]
* [[Gamma]]
* [[Gamma_m_sd|Gamma_m_sd]] (Distribution Variations.ana)
* [[GammaFn]]
* [[GammaI]]
* [[GammaIInv]]
* [[Gaussian]] (Multivariate Distributions.ana)
* [[GCD]] ([[media:GCD function library.ana|GCD function library.ana]])
* [[Geometric]]
* [[GetFract]]
* [[GetProcessInfo]]
* [[GetRegistryValue]]
* [[VarTerm Functions#Function_GetVariableByName| GetVariableByName]]
* [[GoalSeek]] (Optimization Functions.ana)
* [[Gradient]] (Optimization Functions.ana)
* [[GroupedInteger]]
* [[HyperGeometric]]
* [[If-Then-Else]]
* [[Ifall-Then-Else]]
* [[Ifonly-Then-Else]]
* [[If0]]
* [[Ifpos]]
* [[IgnoreWarnings]]
* [[Im]] (Complex Library.ana)
* [[Implied_volatility_c]] (Financial library.ana)
* [[Implied_volatility_p]] (Financial library.ana)
* [[Index Position Operator::@|Index Position Operator: @I, @[I=x] ]] : Get the numeric position of index elements
* [[VarTerm Functions#Function_IndexesOf| IndexesOf]]
* [[Index..Do]]
* [[IndexNames]]
* [[IndexValue]]
* [[InsertRecSql]] (ODBC Library.ana)
* [[Integer]]
* [[Integrate]]
* [[InverseGaussian]] (Distribution Variations.ana)
* [[Invert]]
* [[InvertedWishart]] (Distribution Variations.ana)
* [[InvLogit]] (Generalized Regression.ana)
* [[IPmt]]
* [[Irr]]
* [[IsHandle]]
* [[Data_Type_Functions#Function_IsNaN| IsNaN]]
* [[Data_Type_Functions#Function_IsNotSpecified| IsNotSpecified]]
* [[IsNull]]
* [[Data_Type_Functions#Function_IsNumber| IsNumber]]
* [[Data_Type_Functions#Function_IsReference| IsReference]]
* [[IsResultComputed]]
* [[Data_Type_Functions#Function_IsText| IsText]]
* [[Data_Type_Functions#Function_IsUndef| IsUndef]]
* [[Iterate]]
* [[Join]]
* [[JoinText]]
* [[Kurtosis]]
* [[LDens_InvertedWishart]] (Distribution Densities.ana)
* [[LDens_Wishart]] (Distribution Densities.ana)
* [[LGamma]]
* [[LinearInterp]]
* [[ListOfHandles]]
* [[LL_First]] (Linked List Library.ana)
* [[LL_Length]] (Linked List Library.ana)
* [[LL_Nth]] (Linked List Library.ana)
* [[LL_Push]] (Linked List Library.ana)
* [[LL_Remove_First]] (Linked List Library.ana)
* [[LL_To_Array]] (Linked List Library.ana)
* [[LL_to_RArray]] (Linked List Library.ana)
* [[Ln]]
* [[Local Index Operator::A.I]] : Get an index (usually a local index) of an array
* [[Logistic]]
* [[Logistic_Regression]] (Generalized Regression.ana)
* [[Logit]] (Generalized Regression.ana)
* [[LogNormal]]
* [[Lognormal_m_sd]] (Distribution variations.ana) - obsolete, use [[LogNormal]] (mean:m,stddev:sd)
* [[LogTen]]
* [[Lorenzian]] (Distribution variations.ana)
* [[LpDefine]]
* [[LpFindIIS]]
* [[LpObjSa]]
* [[LpOpt]]
* [[LpRead]]
* [[LpReducedCost]]
* [[LpRhsSa]]
* [[LpShadow]]
* [[LpSlack]]
* [[LpSolution]]
* [[LpStatusNum]]
* [[LpStatusText]]
* [[LpWrite]]
* [[LpWriteIIS]]
* [[Date_Functions#MakeDate.28year.2C_month.2C_day.29| MakeDate]]
* [[MatrixMultiply]]
* [[Functions_Min_and_Max| Max]]
* [[MdArrayToTable]]
* [[MdTable]]
* [[MdxQuery]]
* [[Mean]]
* [[Median]]
* [[MemoryInUseBy]]
* [[Mid]]
* [[Functions_Min_and_Max| Min]]
* [[Mod]]
* [[MonoCubicInterp]]
* [[MsgBox]]
* [[Multinomial]] (Multivariate Distributions.ana)
* [[MultiNormal]] (Multivariate Distributions.ana)
* [[MultiUniform]] (Multivariate Distributions.ana)
* [[NegBinomial]] (Distribution Variations.ana)
* [[NlpDefine]]
* [[Normal]]
* [[Normal_additive_gro]] (Multivariate Distributions.ana)
* [[Normal_compound_gro]] (Multivariate Distributions.ana)
* [[Normal_correl]] (Multivariate Distributions.ana)
* [[Normal_serial_correl]] (Multivariate Distributions.ana)
* [[Normalize]]
* [[Not]]
* [[NPer]]
* [[Npv]]
* [[NumberToText]]
* [[OpenExcelFile]] -- depreciated: use [[SpreadsheetOpen]]
* [[OptEngineInfo]]
* [[OptFindIIS]]
* [[OptGuess]]
* [[OptInfo]]
* [[OptObjective]]
* [[OptObjectiveSa]]
* [[OptRead]]
* [[OptReducedCost]]
* [[OptRhsSa]]
* [[OptScalarToConstraint]]
* [[OptScalarToDecision]]
* [[OptShadow]]
* [[OptSlack]]
* [[OptSolution]]
* [[OptStatusNum]]
* [[OptStatusText]]
* [[OptWrite]]
* [[OptWriteIIS]]
* [[Or]]
* [[Pareto]] (Distribution Variations.ana)
* [[ParseDate]]
* [[ParsedExprFunction]]
* [[ParsedExprParameters]]
* [[ParseNum]] (Flat file library.ana - for Analytica 4.1)
* [[ParseNumber]]
* [[Pdf]]
* [[Permutations]]
* [[Pert]] (Distribution Variations.ana)
* [[Pmt]]
* [[Poisson]]
* [[PolarToC]] (Complex Library.ana)
* [[Index Position Operator::@|Position Operator: @I, @[I=x] ]] : Get the numeric position of index elements
* [[PositionInIndex]]
* [[PPmt]]
* [[Probability]]
* [[ProbBands]]
* [[ProbDist]]
* [[Probit_Regression]] (Generalized Regression.ana)
* [[ProbTable]]
* [[Prob_Bernoulli]] ([[Distribution Densities Library]])
* [[Prob_Binomial]] ([[Distribution Densities Library]])
* [[Prob_ChanceDist]] ([[Distribution Densities Library]])
* [[Prob_Geometric]] ([[Distribution Densities Library]])
* [[Prob_HyperGeometric]] ([[Distribution Densities Library]])
* [[Prob_Poisson]] ([[Distribution Densities Library]])
* [[ProbWilcoxon]]
* [[Product]]
* [[Putoption]] (Financial Library.ana)
* [[Pv]]
* [[Pvgperp]] (Financial Library.ana)
* [[Pvperp]] (Financial Library.ana)
* [[QpDefine]]
* [[Q_infromrec]]
* [[Q_makerect]]
* [[Q_squareinterp]]
* [[Radians]]
* [[Random]]
* [[Rank]]
* [[RankCorrel]]
* [[Rate]]
* [[Rayleigh]] (Distribution variations.ana)
* [[Re]] (Complex Library.ana)
* [[ReadCsvFile]] (Flat File Library.ana)
* [[ReadFromUrl]]
* [[ReadImageFile]]
* [[ReadTextFile]]
* [[Reference Operator::\|Reference Operator: \X]] : Return a reference to X
* [[Reform]]
* [[Regression]]
* [[RegressionDist]] (Multivariate Distributions.ana)
* [[RegressionFitProb]] (Multivariate Distributions.ana)
* [[RegressionNoise]] (Multivariate Distributions.ana)
* [[Round]]
* [[RunConsoleProcess]]
* [[Sample]]
* [[SampleCorrelation]] (Multivariate Distributions.ana)
* [[SampleCovariance]] (Multivariate Distributions.ana)
* [[SaveExcelWorkbook]] -- deprecated: use [[SpreadsheetSave]]
* [[ScanAttFromModelFile]]
* [[SchedulePublish]]
* [[SDeviation]]
* [[SelectText]]
* [[Sequence]]
* [[Sequence Operator|Sequence Operator: first..last]]
* [[SetContains]]
* [[SetDifference]]
* [[SetIntersection]]
* [[SetUnion]]
* [[ShowPdfFile]]
* [[ShowProgressBar]]
* [[Shuffle]]
* [[Sign]]
* [[Trig Functions| Sin]]
* [[SingularValueDecomp]]
* [[Trig Functions| Sinh]]
* [[SipDecode]]
* [[SipEncode]]
* [[Size]]
* [[Skewness]]
* [[Slice]]
* [[Subscript/Slice Operator| Slice Operator: [@I=n] ]]
* [[Smooth_Fractile]] (Distribution variations.ana)
* [[Solve]] (Optimization Functions.ana)
* [[SolverInfo]]
* [[Sort]]
* [[SortIndex]]
* [[Split]]
* [[SplitText]]
* [[SpreadsheetCell]]
* [[SpreadsheetOpen]]
* [[SpreadsheetRange]]
* [[SpreadsheetSave]]
* [[SpreadsheetSetCell]]
* [[SpreadsheetSetRange]]
* [[SqlDriverInfo]]
* [[Sqr]]
* [[Sqrt]]
* [[Statistics]]
* [[StepInterp]]
* [[StringLength]]
* [[StringLowercase]]
* [[StringMixedCase]]
* [[StringReplace]]
* [[StringUpperCase]]
* [[StudentT]]
* [[SubFindString]]
* [[SubIndex]]
* [[Subscript]]
* [[Subscript/Slice Operator| Subscript Operator: [I=x] ]]
* [[Subset]]
* [[SubString]]
* [[SubTable]]
* [[Sum]]
* [[Sys_coordindex]]
* [[Sys_localindex]]
* [[Table]]
* [[Trig Functions| Tan]]
* [[Trig Functions| Tanh]]
* [[TestHeapConsistency]]
* [[Text Concatenation Operator: &|Text Concatenation Operator: A&B]] : Concatenate two text strings
* [[TextLength]]
* [[TextLowerCase]]
* [[TextReplace]]
* [[TextSentenceCase]]
* [[TextTrim]]
* [[TextUpperCase]]
* [[Today]]
* [[Transpose]]
* [[Triangular]]
* [[Triangular_10_50_90]] (Distribution Variations.ana)
* [[Triangular_10_mode_90]] (Distribution Variations.ana)
* [[Truncate]]
* [[Data_Type_Functions#Function_TypeOf| TypeOf]]
* [[Uncumulate]]
* [[Uniform]]
* [[UniformSpherical]] (Multivariate distributions.ana)
* [[Unique]]
* [[Using..Do]]
* [[Var..Do]]
* [[Variance]]
* [[VarTerm]]
* [[Wacc]] (Financial Library.ana)
* [[Wald]] (Distribution Variations.ana)
* [[Warp_Dist]] (Distribution variations.ana)
* [[Weibull]]
* [[WhatIf]]
* [[WhatIfAll]]
* [[While..Do]]
* [[Wilcoxon]]
* [[Wishart]] (Distribution variations.ana)
* [[WorksheetCell]] -- deprecated: use [[SpreadsheetCell]]
* [[WorksheetRange]] -- deprecated: use [[SpreadsheetRange]]
* [[WriteCsvFile]] (Flat file library.ana)
* [[WriteTableSql]] (ODBC Library.ana)
* [[WriteTextFile]]
* [[WriteWorksheetCell]] -- deprecated: use [[SpreadsheetSetCell]]
* [[WriteWorksheetRange]] -- deprecated: use [[SpreadsheetSetRange]]
* [[XIrr]]
* [[XNpv]]
* [[YearFrac]]

JoinText

2012-07-04T17:13:56Z

LonnieTest: /* The All-Null case */

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

[[Category:Text Functions]]

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

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

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

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

=== Optional parameters ===

{| border="0"
! align="left" |
* «separator»
| : || text inserted between each item.
|-
! align="left" |
* «finalSeparator»
| : || Used instead of «separator» between the penultimate and final items.
|-
! align="left" |
* «default»
| : || ''(new in 4.4.3)'' The result value when there are no items to be joined. E.g., when all items are [[Null]].
|-
! align="left" |
* «textForNull»
| : || ''(new in 4.4.3)'' When specified, [[Null]] items are not ignored, and the text provided is used.
|}

= Examples =

Suppose ''A'' is the following array, indexed by ''J''
::{| border="1"
! J → || 1 || 2 || 3 || 4 || 5
|-
!
| "one" || "two" || "three" || "four" || "five"
|}

Then:
<code>
:{| border="0"
| [[JoinText]](A,J)
| → || "onetwothreefourfive"
|-
| [[JoinText]](A,J,',')
| → || "one,two,three,four,five"
|-
| [[JoinText]](A,J,", "," and ")
| → || "one, two, three, four and five"
|-
| [[JoinText]]([[Exp]](J^2),J,', ')
| → || "2.718, 54.6, 8103, 8.886M, 72G"
|}
</code>

'''Treatment of Null'''. Suppose ''B' is the following array indexed by ''J''
::{| border="1"
! J → || 1 || 2 || 3 || 4 || 5
|-
!
| "one" || [[«null»]] || "three" || [[«null»]] || "five"
|}

<code>
:{| border="0"
| [[JoinText]](B,J,",")
| → || "one,three,five"
|-
| [[JoinText]](B,J,",",textForNull:"")
| → || "one,,three,,five"
|-
| [[JoinText]](B,J,",",textForNull:"NULL")
| → || "one,NULL,three,NULL,five"
|-
| [[JoinText]]([Null,Null,Null])
| → || ""
|-
| [[JoinText]]([Null,Null,Null],default:null)
| → || «null»
|-
| [[JoinText]]([])
| → || ""
|-
| [[JoinText]]([],default:"empty")
| → || "empty"
|}
</code>

= Notes =

=== The All-Null case ===

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

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

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

If you want to concatenate all elements in a 2-D array, ignoring all «null» cells, then you'll want to use <code>default:null</code>, e.g:
:<code>[[JoinText]]([[JoinText]](A,I,",",default:null),J,",",default:null)</code>
If you don't use <code>default:null</code> in this case, you'll get an extra comma when an all-null row appears.

= See Also =

* [[SplitText]]
* [[Text Concatenation Operator: &]]

JoinText

2012-07-04T17:12:41Z

LonnieTest: Notes on all-null case

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

[[Category:Text Functions]]

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

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

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

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

=== Optional parameters ===

{| border="0"
! align="left" |
* «separator»
| : || text inserted between each item.
|-
! align="left" |
* «finalSeparator»
| : || Used instead of «separator» between the penultimate and final items.
|-
! align="left" |
* «default»
| : || ''(new in 4.4.3)'' The result value when there are no items to be joined. E.g., when all items are [[Null]].
|-
! align="left" |
* «textForNull»
| : || ''(new in 4.4.3)'' When specified, [[Null]] items are not ignored, and the text provided is used.
|}

= Examples =

Suppose ''A'' is the following array, indexed by ''J''
::{| border="1"
! J → || 1 || 2 || 3 || 4 || 5
|-
!
| "one" || "two" || "three" || "four" || "five"
|}

Then:
<code>
:{| border="0"
| [[JoinText]](A,J)
| → || "onetwothreefourfive"
|-
| [[JoinText]](A,J,',')
| → || "one,two,three,four,five"
|-
| [[JoinText]](A,J,", "," and ")
| → || "one, two, three, four and five"
|-
| [[JoinText]]([[Exp]](J^2),J,', ')
| → || "2.718, 54.6, 8103, 8.886M, 72G"
|}
</code>

'''Treatment of Null'''. Suppose ''B' is the following array indexed by ''J''
::{| border="1"
! J → || 1 || 2 || 3 || 4 || 5
|-
!
| "one" || [[«null»]] || "three" || [[«null»]] || "five"
|}

<code>
:{| border="0"
| [[JoinText]](B,J,",")
| → || "one,three,five"
|-
| [[JoinText]](B,J,",",textForNull:"")
| → || "one,,three,,five"
|-
| [[JoinText]](B,J,",",textForNull:"NULL")
| → || "one,NULL,three,NULL,five"
|-
| [[JoinText]]([Null,Null,Null])
| → || ""
|-
| [[JoinText]]([Null,Null,Null],default:null)
| → || «null»
|-
| [[JoinText]]([])
| → || ""
|-
| [[JoinText]]([],default:"empty")
| → || "empty"
|}
</code>

= Notes =

=== The All-Null case ===

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

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

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

If you want to concatenate all elements in a 2-D array, ignoring all «null» cells, then you'll want to use <code>default:null</code>, e.g:
:<code>[[JoinText]]([[JoinText]](A,I,",",default:null),J,",",default:null)</code>
If you don't use <code>default:null</code> in this case, you'll get an extra comma when an all-null row appears.

= See Also =

* [[SplitText]]
* [[Text Concatenation Operator: &]]

JoinText

2012-07-04T17:03:28Z

LonnieTest:

JoinText

2012-07-04T16:52:25Z

LonnieTest: Refined description, and added some 4.4.3 enhancements

Error Messages/42727

2012-07-03T19:43:30Z

LonnieTest: Redirected page to Error Messages/42728

#REDIRECT [[Error Messages/42728]]

Error Messages/42728

2012-07-03T19:42:41Z

LonnieTest: Wrote description

= Example Error Message =

:The result computed by the Function [[Elasticity]] is unreliable because the Function [[Normal]], called from ''Appreciation'', produces random values. Because ''Appreciation'' is downstream from ''Inflation'', this is likely to cause a misleading random fluctuation when Function [[Elasticity]] explores changes to the value of ''Inflation''. Other distribution function call(s) also appear in ''Maintenance'' and ''Insurance''.

= Cause =

The sensitivity functions [[Elasticity]] and [[Dydx]] compute their results using finite differencing. For example, <code>[[Dydx]](f(x),x)</code> evaluates <code>f(x)</code> and <code>f(x+delta)</code> for a very small value <code>delta</code>. The problem flagged by this warning arises when <code>f(x)</code> involves a random number, thus making the result of <code>f(x)</code> random. A non-random continuous function will usually see a small change from <code>f(x)</code> to <code>f(x+delta)</code> for a small <code>delta</code>, but when the result is random, <code>f(x)</code> is no longer continuous.

To illustrate this, consider a simple example:

Variable ub := 10;
Chance y := [[Uniform]](0,ub)
Variable sens := [[Dydx]](y,ub)

In this example, when <code>y</code> is evaluated as a distribution, its [[Sample]] is a list of numbers between 0 and 10. For example, it might happen that <code>y[Run=1]</code> is 4.415. When [[Dydx]] is evaluates, it sets <code>ub</code> to 10.000001 and evaluates <code>y</code>. The random number generator spits out a new random number, this time between 0 and 10.000001, say <code>y[Run=1]</code> equal to 8.731. With these random numbers, a very large change occurred in the result from the very small change to <code>ub</code>, so that the slope appears to be <code>(8.731-4.415)/0.000001 = 4.316M</code>.

= Remedy =

You should never perform a [[Dydx]] or [[Elasticity]] sensitivity analysis on a model that has a distribution function downstream from the sensitivity input variable.

Distribution (or [[Random]]) functions are not a problem when the distribution function is not downstream from the sensitivity input variable. Consider the following reformulation of the above example:

Variable ub := 10
Chance u := [[Uniform]](0,1)
Variable y := u * ub
Variable sens := [[Dydx]](y,ub)

The computation of <code>y</code> is equivalent to the first example, but the problem with randomness does not occur because the chance variable <code>u</code> is not downstream from <code>ub</code>. Suppose the random sample has <code>u[Run=1]</code> equal to 0.4415, so that <code>y[Run=1]</code> is 4.415 as before. When [[Dydx]] evaluates <code>y</code> with <code>ub := 10.000001</code>, <code>y</code> change by only 0.000004415, so that its derivative is 0.4415 -- a stable number, and not subject to randomness.

= See Also =

* [[Dydx]]
* [[Elasticity]]