Extracts a string of characters from text, starting from the left.

For example, if a product SKU is prefixed with a code of fixed length, you can use the LEFT function to extract this from the rest of the text.

LEFT(Text [, Number of characters]) 

ArgumentData typeDescription
Text

Text

Can be a line item, text constant, or general expression.

The text to extract characters from.
Number of characters (optional)

Number

Can be a line item, property, or expression.

The number of characters to extract from the string.

If you omit this argument, the LEFT function returns only the first, left, character from the text string.

If you use a negative number or zero for this argument, the LEFT function returns a blank result.

If this argument is greater than the number of characters in the Text argument, the LEFT function returns only the characters in the string.

The LEFT function returns a text-formatted result.

LEFT(Product SKU, 3)

In this example, a line item named Product SKU contains a list of strings that identify different products. Each SKU starts with a three character string that describes the product category.

This formula uses the Product SKU line item for the Text argument and 3 for the Number of characters argument. As a result, the formula returns the first three characters for each product SKU as a text-formatted result.

The LEFT function cannot be used with list items. Convert list items to text-formatted with the NAME function if you need to use the LEFT function with them.

In Polaris, the LEFT function behaves as expected with all text values, including those that contain composite characters or characters from outside the Basic Multilingual Plane (BMP).

In the Classic Engine, the LEFT function considers the length of:

  • Unicode characters from within the BMP to be 1
  • Unicode characters from outside the BMP to be 2
  • The length of composite characters (such as those with accents or diacritic marks) to be equal to the number of components

In this example, a Clothing list displays on columns. It contains four items, HatsShirtsShorts, and Trousers.

Three text-formatted line items display on rows, Red Product, Blue Product, and Yellow Product. These contain product names. There is also one list-formatted line item, Clothing List, which contains product types. These line items contain the values used for the Text argument.

The bottom four rows contain formulas that use the LEFT function to extract characters from the left of the text strings.


HatsShirtsShortsTrousers
Red ProductRed HatsRed ShirtsRed ShortsRed Trousers
Blue ProductBlue HatsBlue ShirtsBlue ShortsBlue Trousers
Yellow ProductYellow HatsYellow ShirtsYellow ShortsYellow Trousers
Clothing ListHatsShirtsShortsTrousers
LEFT(Red Product, 3)RedRedRedRed
LEFT(Blue Product, 7)Blue HaBlue ShBlue ShBlue Tr
LEFT(Yellow Product, 10)Yellow HatYellow ShiYellow ShoYellow Tro
LEFT(NAME(Clothing List), 3)HatShiShoTro

You can use the ITEM function to return the list-formatted column names. Then, you can use the NAME function to convert the names to be text-formatted, which is compatible with the LEFT function.

In this example, the Fruit list displays on columns, and two line items display on rows. Both line items contain formulas.


ApplesPeachesBananasPearsCarrotsCucumbersLettuce
ITEM(Products)ApplesPeachesBananasPearsCarrotsCucumbersLettuce
LEFT(NAME(ITEM(Products)), 5)ApplePeachBananPearsCarroCucumLettu

In this example, 5 is used for the the Number of characters argument, so the formula returns the first five letters of the list-formatted Products strings.

LEFT("Favorite Team", 8) 

This example uses the LEFT function with a text string typed directly into the formula. It uses 8 for the Number of characters argument. This means it returns Favorite, the first eight characters of the text string.