Left

Left(string, count)

<h3>Left Example</h3>

<cfif IsDefined("Form.MyText")>
<!--- if len is 0, then err --->
   <cfif Len(form.myText) is not 0>
      <cfif Len(form.myText) LTE form.RemoveChars>
         <p>Your string <cfoutput>#form.myText#</cfoutput>
         only has <cfoutput>#Len(form.myText)#</cfoutput>
         characters. You cannot output the <cfoutput>#form.removeChars#</cfoutput>
         leftmost characters of this string because it is not long enough
      <cfelse>
         <p>Your original string: <cfoutput>#form.myText#</cfoutput>
         <p>Your changed string, showing only the <cfoutput>#form.removeChars#
</cfoutput> leftmost characters:
         <cfoutput>#Left(Form.myText, form.removeChars)#</cfoutput>
      </cfif>
   <cfelse>
      <p>Please enter a string
   </cfif>
</cfif>

<form action="#CGI.ScriptName#" method="POST">
<p>Type in some text
<br>
<input type="Text" name="MyText">
<p>How many characters from the left do you want to show?
<select name="RemoveChars">
   <option value="1">1
   <option value="3" selected>3
   <option value="5">5
   <option value="7">7
   <option value="9">9</select>
<input type="Submit" name="Remove characters">
</form>

Comments

joonstar said on Oct 25, 2003 at 4:21 PM :

#trim(left(myText,5))# shows only 5 characters from the left.
I like to hide 5 characters from the left and show the rest of it.

Sarge said on Mar 19, 2004 at 4:17 PM :

Consider alphabetizing the related functions.

Sarge said on Mar 19, 2004 at 4:25 PM :

Consider modify the definition to say:

Returns the count of characters from the beginning of the string argument.

String; the leftmost count characters at the beginning of the string.

Sarge said on Mar 20, 2004 at 9:23 AM :

We are working to improve the examples in the ColdFusion reference pages. We propose to replace the current example on this page with the the following example. If you have any comments on this example, add them to this page.

This example shows how to use the left function to return the leftmost count of characters.

<h3>Left Example</h3>

<cfif IsDefined("Form.myText")>
<!--- If len returns 0 (zero), then show error message. --->
<cfif Len(Form.myText)>
<cfif Len(Form.myText) LTE Form.RemoveChars>
<cfoutput><p style="color: red; font-weight: bold">Your string #Form.myText#
only has #Len(Form.myText)#
characters. You cannot output the #Form.removeChars#
leftmost characters of this string because it is not long enough.</p></cfoutput>
<cfelse>
<cfoutput><p>Your original string: <strong>#Form.myText#</strong></p>
<p>Your changed string, showing only the <strong>#Form.removeChars#</strong> leftmost characters:
<strong>#Left(Form.myText, Form.removeChars)#</strong></p></cfoutput>
</cfif>
<cfelse>
<p style="color: red; font-weight: bold">Please enter a string of more than 0 (zero) characters.</p>
</cfif>
</cfif>

<form action="<cfoutput>#CGI.ScriptName#</cfoutput>" method="POST">
<p>Type in some text<br />
<input type="Text" name="myText"></p>
<p>How many characters from the left do you want to show?
<select name="RemoveChars">
<option value="1">1
<option value="3" selected>3
<option value="5">5
<option value="7">7
<option value="9">9</select>
<input type="Submit" name="Submit" value="Remove characters"></p>
</form>

a440guy said on Jun 23, 2004 at 12:43 PM :

Sarge, about your suggestions to modify the definition:

"Returns the count of characters" is no good. A "count" is a cardinal number or zero. Thus, it means that you are returning a number that is the count of the characters from the beginning of the string. From the beginning to where? The existing description is much better, the only thing it needs is a better word for "count". My suggestion: "returns the leftmost n characters of a string. You should italicize "n". Of course, you must use "n" instead of "count" throughout the page. Why use "n"? It is commonly used to represent a number in Mathematics and Computer Science. Even the lay person can readily recognized is as being a number, especially if it is used that way throughout the documentation. "count" could be anything, but the word suggest that something was counted, which is not the case.

And what does this mean: "the leftmost count characters at the beginning of the string"?. Please explain what the leftmost count characters at the end of the string would be, or what the rightmost count characters at the beginning (or middle) of the string would be. If you say "leftmost" you don't need to say "beginning".

Other thoughts about this page (and this applies to other pages that I have reviewed):

The top line is the name of the function. The second line describes the return value (we know that because it begins with the word "returns"). The third line? We don't know what it is. What does "String;" mean? Is "Left" a string? (It's followed by a semi-colon, so it can stand alone.) Is it the parameter shown in the usage line below? The semi-colon also has the effect of signaling that the following clause is closely related to the first clause, perhaps an elaboration of the first clause. And again, the use of the word "count" makes for an ungramatical and confusing phrase. If you are going to use a real word as a SYMBOL for an element of syntax, you should emphaze it somehow, such as printing it in italics, bold, or as is done in some forms of BNF notation, surrounding it with angle brackets. Maybe this third line is meant to describe the data type of the return value. If so, then the second phrase does not belong. Regardless, this phrase is redundant to the second line. Frankly, I don't see how this third line adds anything at all to the page. In my opinion, it should be completely eliminated.

On the other hand, if there is a purpose for this third line, please do something to explain that. Perhaps a label in front of it would make it clear. In other pages, it seems that this third line describes the return value. If that's the case, then this line needs a bold label like this: "Returns:".

The next line, "String functions", is in the wrong place. Apparently, you are trying to tell us what "category" the Left function belongs to. This line needs a label, too ("Category:"). Even so, it's in the wrong place, mixed in with the function name, description, return value, and usage. it should be moved to a spot immediately before the list of related functions (as they are in the same category).

In the table containing the columns labeled "Parameter" and "Description":

Even though it's clear that the first column contains parameters, it would be a good idea to print the parameter symbols in italics so as to be consistent with the function description, return value description, and usage (syntax) definition. In those lines, you have forward references in the form of symbols 'string' and 'count'. This table is where you define what those symbols mean. To clearly tie the symbols to their definitions, they should have the same visual appearance.

The other column in this table is labeled "Description". Although you may wish to retain this label, keep in mind that this column should hold definitions. If you wish to add explanatory or descriptive materal, that's fine. But, you must ensure that you have, first and foremost, _defined_ the parameter, precisely and unambigously. In this case, I am happy to see that you have indeed included definitions. However, unambigous they are not. To what does "one" refer in "A string or a variable that contains one." LIkewise for "A positive integer or a variable that contains one."

I guess I've said enough ;-) (Whew!)

pete_freitag said on Jan 6, 2005 at 10:11 AM :

The docs should also point out that if the Count is greater than the length of the string, the original string is returned.