Caché Basic Reference
Left
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Returns or replaces a specified number of characters from the left end of a string.
Synopsis
Left(string,length)

Left(string,length)=value
Arguments
string String expression from which the leftmost characters are returned.
length Numeric expression that evaluates to a positive integer indicating how many characters from the beginning of string to return or replace. Fractional numbers are truncated to an integer. If length is 0 or a negative number, Left returns a zero-length string (""). If length is 0 or a negative number, Left performs no replacement. If length is greater than or equal to the number of characters in string, the entire string is returned (or replaced). No padding is performed.
value The value used to replace the specified character(s) at the beginning of string. An expression that evaluates to a string.
Description
The Left function can be used in two ways:
Left(string,length) returns the leftmost character(s) of string. The length argument specifies how many characters of string to return. If length is 0 or a negative number, Left returns the empty string (""). If you specify a length greater than the length of string, the entire string is returned.
Left(string,length)=value replaces the leftmost character(s) of string with value. The length argument specifies how many characters of string to replace. If length is 0 or a negative number, string is unchanged. This is true even when string is the empty string (""). If length is greater than the length of string, string is replaced by value.
To determine the number of characters in string, use the Len function.
The Right function returns (or replaces) the specified number of characters from the end (right end) of a string. The Mid function returns (or replaces) the specified number of characters from a specified starting point within a string.
Examples
The following example uses the Left function to return the first three characters of mystr, the first 99 characters (in this case, all of the characters), and the first 0 characters:
Dim mystr
mystr = "InterSystems"
Println "length 3:",Left(mystr,3)   ' Returns "Int"
Println "length 99:",Left(mystr,99) ' Returns "InterSystems"
Println "length 0:",Left(mystr,0)   ' Returns ""
 
The following example uses the Left function to replace the first three characters of mystr with a five-character string:
Dim mystr
mystr = "NtrSystems"
PrintLn mystr
Left(mystr,3)="Inter"
PrintLn mystr
 
The following example deletes (replaces with the null string) the first three characters of mystr:
Dim mystr
mystr = "NtrSystems"
PrintLn mystr
Left(mystr,3)=""
PrintLn mystr
 
The following example replaces all of the characters of mystr, because length is greater than the length of mystr:
Dim mystr
mystr = "Oracle"
PrintLn mystr
Left(mystr,99)="InterSystems"
PrintLn mystr
 
The following example shows that length=0 has no effect on mystr:
Dim mystr
Dim empstr
mystr = "InterSystems"
empstr = ""
PrintLn mystr
Left(mystr,0)="Bongo"
PrintLn "string out:",mystr
Left(empstr,0)="BongoSystems"
PrintLn "string out:",empstr
 
See Also