====== FieldStore function  ======


 
==== Description ====
 
Use to replace, delete, or insert substrings in a string.
 
==== Syntax ====
 
//result// = **FieldStore**(//source_string, delimiter, occurrence, field, string//)
 
==== Parameters ====
 
The FieldStore function has the following parameters.

^Parameter^Description^
|//source_string//|Specifies the string that is to be searched, then modified.|
|//Delimiter//|Any single ASCII character including field, value, or subvalue marks. This value determines what constitutes a "field" in the values of both //source_string// and //string//.|
|//Occurrence//|Processing starts at the ordinal substring designated by //occurrence//. The value of //delimiter// determines the end of each "field." If the number of substrings within //source_string// is less than the value of occurrence, //source_string// will be padded with the necessary number of null substrings, before FieldStore is executed.|
|//Field//|Specifies the number of substrings in string to apply to //source_string//. As with //source_string//, the value of //delimiter// determines the end of a substring. The value of //field// determines the operation in //source_string//.\\ \\ __Value__ __Description__\\ Positive number - Moves that number of substrings from string to //source_string//.\\ 0 - Inserts the entire string in //source_string//. The insertion occurs at the substring indicated by //occurrence.//\\ Negative number - Inserts the entire string in //source_string//. The field specifies the number of substrings to replace in //source_string.//|
|//String//|Contains the new string values to store in //source_string//.|

 
==== See Also ====
 
[[field|Field()]], [[replace|Replace()]], [[angle_brackets_operator|< > (Angle Brackets operator]]), [[delete_function|Delete()]], [[insert|Insert()]]
 
==== Example ====
 
<code>
/* The following routine changes a phone number, where the area code remains the same. */

source  = '206-111-2222'   ;* old number
delimiter = '-'
occur   = 2     ;* start with 2nd field
field   = 2     ;* replace 2 fields
string  = '333-4444'    ;* new number
new_number = FieldStore (source, delimiter, occur, field, string)
</code>

<code>
* Example using fieldstor to insert, replace, and delete the second item in a list
      list = 'AAA BBB CCC DDD'     
      value = 'XXX'
      delim = " "
      nth_pos = 2
      
      If nth_pos Lt 0 Then Return ""
        
      * Insert a value before the nth
      inserted = fieldstore(list, delim, nth_pos, 0, value) ; * 'XXX AAA BBB CCC DDD'
      replaced = fieldstore(list, delim, nth_pos, 1, value) ; * 'AAA XXX CCC DDD'
      
      * Deleting is unintuitive. To delete an item, you can replace two items with one
      * For example, to delete the nth element, replace n-1th and the nth with the n-1th
      * A negative index in the 4th parameter indicates removal. 
      If nth_pos Gt 1 Then
         prev_pos = nth_pos - 1
         deleted  = fieldstore(list, delim, prev_pos, -2, Field(list, delim, prev_pos) ) ; * 'AAA CCC DDD'
      End Else
         * deleting the lead item, use field to get everything but the first item
         deleted  = field(list, delim, 2, Fieldcount(list, delim ) )
      End
</code>