String Expressions

String expressions

String expressions are useful for

creating descriptive texts associated with particular set elements and identifiers, or
forming customized messages for display in the graphical user interface or in output reports.

This section discusses all available string expressions in AIMMS.

Syntax

string-expression:

The format of list expressions are the same for string-valued and numerical expressions. They are discussed in List Expressions.

String Operators

String operators

There are three binary string operators in AIMMS, string concatenation (+ operator), string subtraction (- operator), and string repetition (* operator). There are no unary string operators.

String concatenation

The simplest form of composing strings in AIMMS is by the concatenation of two existing strings. String concatenation is represented as a simple addition of strings by means of the + operator.

String subtraction

In addition to string concatenation, AIMMS also supports subtraction of two strings by means of the - operator. The result of the operation \(s_1 - s_2\) where \(s_1\) and \(s_2\) are string expressions will be the substring of \(s_1\) obtained by

omitting \(s_2\) on the right of \(s_1\) when \(s_1\) ends in the string \(s_2\), or
just \(s_1\) otherwise.

String repetition

You can use the multiplication operator * to obtain the string that is the result of a given number of repetitions of a string. The left-hand operand of the repetition operator * must be a string expression, while the right-hand operand must be an integer numerical expression.

Examples

The following examples illustrate some basic string manipulations in AIMMS.

"This is "     + "a string"            ! "This is a string"
"Filename.txt" - ".txt"                ! "Filename"
"Filename"     - ".txt"                ! "Filename"
"--"           * 5                     ! "----------"

Formatting Strings

The function FormatString

With the FormatString function you can compose a string that is built up from combinations of numbers, strings and set elements. Its arguments are:

a format string, which specifies how the string is composed, and
one or more arguments (number, string or element) which are used to form the string as specified.

The format string

The first argument of the function FormatString is a mixture of ordinary text plus conversion specifiers for each of the subsequent arguments. A conversion specifier is a code to indicate that data of a specified type is to be inserted as text. Each conversion specifier starts with the % character followed by a letter indicating its type. The conversion specifier for every argument type are given in this table.

Conversion specifiers	Argument type
`%s`	String expression
`%e`	Element expression
`%f`	Floating point number
`%g`	Exponential format number
`%i`	Integer expression
`%n`	Numerical expression
`%u`	Unit expression
`%%`	% sign

Floating point vs. exponential format

When using the %f or %g conversion specifier you explicitly choose a floating point or exponential format, respectively. The %n conversion specifier makes this choice for you. If the absolute value of the corresponding argument is greater or equal to 1, %n assures that you get the shortest representation of %f or %g (or even %i if the argument value is integral). However when a non zero width is specified, AIMMS assumes that the alignment of the decimal point is important and thus %n will stick to the use of the floating point format as long as that fits within the given width. If the absolute value of the corresponding argument is less than 1, %n uses the floating point format as long as the result shows at least 1 significant digit.

Example

In the example below, the current value of the parameter SmallVal and LargeVal are 10 and 20, the current value of CapitalCity is the element 'Amsterdam', and UnitPar is a unit-valued parameter with value kton/hr. The following calls to FormatString illustrate its use.

FormatString("The numbers %i and %i", 10, 20)                ! "The numbers 10 and 20"
FormatString("The numbers %i and %i", SmallVal, LargeVal)    ! "The numbers 10 and 20"
FormatString("The string %s", "is printed")                  ! "The string is printed"
FormatString("The element %e", CapitalCity)                  ! "The element Amsterdam"
FormatString("The unit is %u", UnitPar)                      ! "The unit is kton/hr"
FormatString("The number %n", 4*ArcTan(1))                   ! "The number 3.141"
FormatString("The large number %n", 1e+6)                    ! "The large number 1.000e+06"
FormatString("The integer %n", 10)                           ! "The integer 10"
FormatString("The fraction %n", 0.01)                        ! "The fraction 0.010"
FormatString("The fraction %n", 0.0001)                      ! "The fraction 1.000e-04"

Modification flags

By default, AIMMS will use a default representation for arguments of each type. By modifying the conversion specifier, you further dictate the manner in which a particular argument of the FormatString function is printed. This is done by inserting modification flags in between the %-sign and the conversion character. The following modification directives can be added:

flags:

<
for left alignment

<>
for centered alignment

>
for right alignment

+
add a plus sign (nonnegative numbers)

␣
add a space (instead of the above + sign)

0
fill with zeroes (right-aligned numbers only)

t
print number using thousand separators, using local convention for both the thousand separator and decimal separator. Controlling these separators is via the options Number 1000 separator and Number decimal separator.
field width: the converted argument will be printed in a field of at least this width, or wider if necessary
dot: separating the field width from the precision
precision: the number of decimals for numbers, or the maximal number of characters for strings or set elements.

Note the order

It is important to note that the modification flags must be inserted in the order as described above.

Field width and precision

Both the field width and precision of a conversion specifier can be either an integer constant, or a wildcard, *. In the latter case the FormatString expects one additional integer argument for each wildcard just before the argument of the associated conversion specifier. This allows you to compute and specify either the field width or precision in a dynamic manner. If you do not specify a precision as modification directive, the default precision is taken from the option Listing_number_precision. Similarly, the default width is taken from the option Listing_number_width.

Example

The following calls to FormatString illustrate the use of modification flags.

FormatString("The number %>+08i", 10)               ! "The number +0000010"
FormatString("The number %>t8i", 100000)            ! "The number  100,000"
FormatString("The number %> 8.2n", 4*ArcTan(1))     ! "The number     3.14"
FormatString("The number %> *.*n", 8,2,4*ArcTan(1)) ! "The number     3.14"
FormatString("The element %<5e", CapitalCity)       ! "The element Amsterdam"
FormatString("The element %<>5.3e", CapitalCity)    ! "The element  Ams "
FormatString("The large number %10.1n", 1e+6)       ! "The large number  1000000.0"

Special characters

AIMMS offers a number of special characters to allow you to use the full range of characters in composing strings. These special characters are contained in this table.

Table 6 Special characters
Special character	text code	Meaning
`\f`	FF	Form feed
`\t`	HT	Horizontal tab
`\n`	LF	Newline character
`\"`	`"`	Double quote
`\\`	`\`	Backslash
`\`\(n\)	\(n\)	character \(n\) (\(001\leq n\leq 65535\))

Example

Examples of the use of special characters within FormatString follow.

FormatString("%i \037 \t %i %%", 10, 11)     ! "10 %       11 %"
FormatString("This is a \"%s\" ", "string")  ! "This is a "string" "

Case conversion functions

With the functions StringToUpper, StringToLower and StringCapitalize you can convert the case of a string to upper case, to lower case, or capitalize it, as illustrated in the following example.

StringToUpper("Convert to upper case")    ! "CONVERT TO UPPER CASE"
StringToLower("CONVERT to lower case")    ! "convert to lower case"
StringCapitalize("capitaLIZED senTENCE")  ! "Capitalized sentence"

String Manipulation

Other string related functions

In addition to the FormatString function, AIMMS offers a number of other functions for string manipulation. They are:

Substring to obtain a substring of a particular string,
StringLength to determine the length of a particular string,
FindString to obtain the position of the first occurrence of a particular substring,
FindNthString to obtain the position of the \(n\)-th occurrence of a particular substring, and
StringOccurrences to obtain the number of occurrences of a particular substring.

The function SubString

With the SubString function you can obtain a substring from a particular begin position \(m\) to an end position \(n\) (or to the end of the string if the requested end position exceeds the total string length). The positions \(m\) and \(n\) can both be negative (but with \(m \leq n\)), in which case AIMMS will start counting backwards from the end of the string. Examples are:

SubString("Take a substring of me", 8, 16)    ! returns "substring"
SubString("Take a substring of me", 18, 100)  ! returns "of me"
SubString("Take a substring of me", -5, -1)   ! returns "of me"

The function StringLength

The function StringLength can be used to determine the length of a string in AIMMS. The function will return 0 for an empty string, and the total number of characters for a nonempty string. An example follows.

StringLength("Guess my length")               ! returns 15

The functions FindString and FindNthString

With the functions FindString and FindNthString you can determine the position of the second argument, the key, within the first argument, the search string. The functions return zero if the key is not contained in the search string. The function FindString returns the position of the first occurrence of the key in the search string starting from the left, while the function FindNthString will return the position of the \(n\)-th appearance of the key. If \(n\) is negative, the function FindNthString will search backwards starting from the right. Examples are:

FindString      ("Find a string in a string", "string"     )  ! returns 8
FindNthString   ("Find a string in a string", "string",  2 )  ! returns 20
FindNthString   ("Find a string in a string", "string", -1 )  ! returns 20

FindString      ("Find a string in a string", "this string")  ! returns 0
FindNthString   ("Find a string in a string", "string",  3 )  ! returns 0

Case sensitivity

By default, the functions FindString and FindNthString will use a case sensitive string comparison when searching for the key. You can modify this behavior through the option Case_Sensitive_String_Comparison.

The function StringOccurrences

The function StringOccurrences allows you to determine the number of occurrences of the second argument, the key, within the first argument, the search string. You can use this function, for instance, to delimit the number of calls to the function FindNthString a priori. An example follows.

StringOccurrences("Find a string in a string", "string"     )  ! returns 2

Converting Strings to Set Elements

Converting strings to set elements

Converting strings to new elements to or renaming existing elements in a set is not an uncommon action when end-users of your application are entering new element interactively or when you are obtaining strings (to be used as set elements) from other applications through external procedures. AIMMS offers the following support for dealing with such situations:

the procedure SetElementAdd to add a new element to a set,
the procedure SetElementRename to rename an existing element in a set, and
the function StringToElement to convert strings to set elements.

Adding new set elements

The procedure SetElementAdd lets you add new elements to a set. Its arguments are:

the set to which you want to add the new element,
an element parameter into set which holds the new element after addition, and
the stringname of the new element to be added.

When you apply SetElementAdd to a root set, the element will be added to that root set. When you apply it to a subset, the element will be added to the subset as well as to all its supersets, up to and including its associated root set.

Renaming set elements

Through the procedure SetElementRename you can provide a new name for an existing element in a particular set whenever this is necessary in your application. Its arguments are:

the set which contains the element to be renamed,
the element to be renamed, and
the stringname to which the element should be renamed.

After renaming the element, all data defined over the old element name will be available under the new element name.

The function StringToElement

With the function StringToElement you can convert string arguments into (existing) elements of a set. If there is no such element, the function evaluates to the empty element. Its arguments are:

the set from which the element corresponding to stringname must be returned,
the stringname for which you want to retrieve the corresponding element, and
the optional create argument (values 0 or 1, with a default of 0) indicating whether nonexisting elements must be added to the set.

With the create argument set to 1, a call to StringToElement will always return an element in set. Alternatively to setting the create argument to 1, you can call the procedure SetElementAdd to add the element to the set.

Example

The following example illustrates the combined use of StringToElement and SetElementAdd. It checks for the existence of the string parameter CityString in the set Cities, and adds it if necessary.

ThisCity := StringToElement( Cities, CityString );
if ( not ThisCity ) then
   SetElementAdd( Cities, ThisCity, CityString );
endif;

Alternatively, you can combine both statements by setting the optional create argument of the function StringToElement to 1.

ThisCity := StringToElement( Cities, CityString, create: 1 );

Converting element to string

Reversely, you can use the %e specifier in the FormatString function to get a pure textual representation of a set element, as illustrated in the following assignment.

CityString := FormatString("%e", ThisCity );

String Expressions

String Operators

Formatting Strings

String Manipulation

Converting Strings to Set Elements

Docs

Product

Support