====== Using the Brackets Operator for Extraction ======


=== Description ===

Extracts a substring from a string. Does not affect the original string.

=== Syntax ===


//variable//**[**//start//, //length, <byteOffsetFlag>//**]**

=== Remarks ===

The brackets operator has the following parameters when used for extraction.


^ Parameter     ^ Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ^
| //variable//  | Contains the string on which the extraction operation is performed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| //start//     | A positive or negative integer.\\ \\ If //start// is a positive number, the operation will begin at the character in that position, counting from the first character or space at the beginning of the string.\\ If //start// is a negative number, the operation will begin at the character in that position, counting from the last character or space at the end of the string.\\ If //start// is 0 (zero) or 1, the operation will begin with the first character or space at the beginning of the string.|
| //length//    | Number of characters to extract, beginning from //start//.\\ Each space and character within the string is counted as a character position. Also, note that the value specified for //length// includes the character position specified by //start//.\\ \\ If //length// begins with 'F', then the extraction process begins at //start//, and continues forward until the character following F is found. The character following F, which acts as a delimiter, is not included in the extraction.\\ If //length// begins with 'B', the extraction process proceeds backward, until the delimiter is found.\\ **Note**: If //length// is a character, and neither "F" nor "B" prefixes the character, an "F" is assumed.|
| byteOffsetflag  | Optional.  When set to TRUE$, the //start// parameter is treated as a byte-offset position rather than a character position.  Using a byte-offset offers better performance in a UTF8 application when used with the [[[guides:programming:programmers_reference_manual:bcol1|BCol1()]] and [[[guides:programming:programmers_reference_manual:bcol2|BCol2()]] operators.|

=== Remarks ===

After the extract operator, you can call [[[guides:programming:programmers_reference_manual:col1|COL1()]] and [[[guides:programming:programmers_reference_manual:col2|COL2()]] operators to find the start and end character positions of the operation.  The [[[guides:programming:programmers_reference_manual:bcol1|BCol1()]] and [[[guides:programming:programmers_reference_manual:bcol2|BCol2()]] operators return the byte-offset starting and ending positions.


=== Example ===

<code>

* Some simple examples

a = "this is a test"
b = a[2,3]     ; * "his"
c = a[-3,3]    ; * "est"
d = a[4,"t"]   ; * "s is a"

* Get the first or last word
e = a[1,' ']   ; * "this"
f = a[-1,'B '] ; * "test"

</code> 

<code>
* Using the col2() operator to extract successive elements of a delimited string
appID   = reposID[1,"*"]
typeID  = reposID[col2()+1,"*"]
classID = reposID[col2()+1,"*"]
entID   = reposID[col2()+1,@fm]
</code>

=== See Also ===

[[[guides:programming:programmers_reference_manual:extracting_a_substring]], [[[guides:programming:programmers_reference_manual:col1|COL1()]], [[[guides:programming:programmers_reference_manual:col2|COL2()]], [[[guides:programming:programmers_reference_manual:bcol1|BCol1()]], [[[guides:programming:programmers_reference_manual:bcol1|BCol2()]]

For more details, please refer to [[http://sprezzblog.blogspot.com/2010/03/utf8-and-extended-string-operators.html|this blog post]]