:orphan:

.. ****************************************************************************
.. CUI
..
.. The Advanced Framework for Simulation, Integration, and Modeling (AFSIM)
..
.. The use, dissemination or disclosure of data in this file is subject to
.. limitation or restriction. See accompanying README and LICENSE for details.
.. ****************************************************************************

string
------

.. class:: string

:class:`string` is a basic type in the scripting language that encapsulates a sequence of characters.

Conversions
===========

Strings may be converted back and forth between numeric types and strings by using 'casting' operators::

 string sValue;

 int iValue = 42;
 iValue = iValue + 4;
 sValue = (string) iValue;     // sValue now contains the string "46"
 iValue = (int) sValue;        // iValue now contains the integer 46

 double dValue = 12.345;
 dValue = dValue - 2.0;
 sValue = (string) dValue;     // sValue now contains the string "10.345"
 dValue = (double) sValue;     // dValue now contains the double 10.345

Methods
=======

.. method:: int Length()
   
   The current number of characters in the string.

.. method:: bool Contains(string aSubString)
   
   Returns true if the string contains the provided sub-string.

.. method:: bool StartsWith(string aSubString)
   
   Returns true if the string starts with the provided sub-string.

.. method:: bool EndsWith(string aSubString)
   
   Returns true if the string ends with the provided sub-string.

.. method:: string Substring(int aStart)
            string Substring(int aStart, int aEnd)
   
   Returns a substring of the string.  aStart and aEnd define the index range of the substring returned.  If aEnd is not
   specified, it is the length of the string.
   Indices should be in the range [-length + 1, length - 1].  A negative index is the index from the end of the string.::

    "abcd".Substring(1,-1);      # Returns "bc"
    "abcd".Substring(3);         # Returns "d"
    "abcd".Substring(-1);        # Returns "d"

.. method:: Array<string> Split()
            Array<string> Split(string aDelimiter)
   
   Returns an array of strings containing substrings which are divided by a delimiter.::

    "a,b,c".Split(",");          # Returns {"a", "b", "c"}

   If no delimiter is provided, contiguous whitespace is used::

    "a   b c".Split();           # Returns {"a", "b", "c"}

.. method:: string Join(Array<string> aWords)
   
   Concatenates an array of strings into one single string, using this string as the delimiter.::

    Array<string> words = {"a", "b", "c"};
    "<".Join(words);             # Returns "a<b<c"

.. method:: string Strip()
            string Strip(string aStrippedCharacters)
   
   Returns a string with some leading and trailing characters removed.  Strip() removes any whitespace characters from the
   ends of the string, and Strip(string) removes any of the specified characters from the string.::

    " a bc d  ".Strip();         # Returns "a bc d"
    "(1.0)".Strip("()");         # Returns "1.0"

.. method:: string Upper()
   
   Returns the string in upper-case. ::

    "aBc".Upper()                # Returns "ABC"

.. method:: string Lower()
   
   Returns the string in lower-case. ::

    "AbC".Lower()                # Returns "abc"

.. method:: string Replace(string aSearch,string aReplace)
   
   Returns the string with all instances of 'aSearch' with 'aReplace'. :: 

    // displays "see stripe run, run stripe run"
    writeln("see spot run, run spot run".Replace("spot", "stripe"));
    
.. method:: string Pad(int aWidth)
            string Pad(int aWidth, string aPadChar)
            
   Returns a string that is the current value of the string padded to a specified width. The absolute value of 'aWidth'
   specifies the desired width. If 'aWidth' is positive the padding will occur on the left, and if it is negative the padding
   will occur on the right. If the input string is already greater than the desired width then no padding will be added.
   
   In the first form the padding character is the blank (' '). In the second form the padding character will be the first
   character of 'aPadChar'.
   
   Examples::
   
   "abc".Pad(5)                  # Returns "  abc"
   "abc".Pad(-5)                 # Returns "abc  "
   "abc".Pad(5, "#")             # Returns "##abc"
   "abc".Pad(-5, "#")            # Returns "abc##"