SUBSTR( ) Function

  • Article

Returns a character string from the given character expression or memo field, starting at a specified position in the character expression or memo field and continuing for a specified number of characters.

SUBSTR(cExpression, nStartPosition [, nCharactersReturned])

Parameters

  • cExpression
    Specifies the character expression or memo field from which the character string is returned.

  • nStartPosition
    Specifies the position in the character expression or memo field cExpression from where the character string is returned. The first character of cExpression is position 1.

    Note

    If nStartPosition is greater than the number of characters in cExpression, SUBSTR( )returns an empty string ("").

  • nCharactersReturned
    Specifies the number of characters to return from cExpression. If you omit nCharactersReturned, characters are returned until the end of the character expression is reached.

Return Value

Character. SUBSTR( ) returns a character string.

Note

SUBSTR( ) will not return a value for a memo field when issued in the Debug window. To return a value in the Debug window, place the memo field name within ALLTRIM( ), and place ALLTRIM( ) within SUBSTR( ).

Remarks

When using SUBSTR( ) with memo fields in a SQL SELECT command, include the PADR( ) function in SUBSTR( ) so that empty or variable length memo fields produce consistent results when converted to character strings.

Example

The following example stores string 'abcdefghijklm' to the variable myString using the STORE command. CLEAR clears the main Visual FoxPro window. Beginning with the first character as specified by nStartPosition = 1, SUBSTR( ) displays the string 'abcde' with five characters as specified by nCharactersReturned = 5. SUBSTR( ) then displays the string 'fghijklm' beginning with the sixth character in the string as specified by nStartPosition = 6 until the end of the character expression is reached as specified by the omission of a value for nCharactersReturned.

STORE 'abcdefghijklm' TO myString
CLEAR
? SUBSTR(myString, 1, 5)  
? SUBSTR(myString, 6)

See Also

Reference

AT( ) Function

AT_C( ) Function

ATC( ) Function

ATCC( ) Function

ATCLINE( ) Function

ATLINE( ) Function

LEFT( ) Function

PADL( ) | PADR( ) | PADC( ) Functions

RAT( ) Function

RATLINE( ) Function

RIGHT( ) Function

LEFTC( ) Function

RIGHTC( ) Function

SUBSTRC( ) Function

STREXTRACT( ) Function

STRTRAN( ) Function

STUFF( ) Function

Other Resources

Functions

Language Reference (Visual FoxPro)