|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The Structure of Expressions
|
|
|
|
This section is about the objects that can be used to build expressions. The objects and their properties are described in detail. Knowledge of the material in this section will enable the construction of powerful and flexible ColdFusion expressions.
The basic terms -- numbers, strings, Boolean (logical) values, date-and-time objects, lists, and complex objects such as arrays, structures, queries, and COM objects -- are the simplest expressions that exist. This section defines the meaning and properties of each of these terms.
|
|
|
|
Numbers |
|
|
|
ColdFusion supports both integer numbers (numbers with no decimal part, for example, 14) and real numbers (numbers with a decimal part, such as 3.127). Real numbers are also known as floating-point numbers. Integer and real numbers can be freely intermixed in expressions, so, for example, 1.2 + 3 evaluates to 4.2 .
ColdFusion can work with both very large and very small real numbers. The range of ColdFusion numbers is approximately ±10300, or ±1 with 300 zeros after it. Most operations are accurate to 12 digits after the decimal point.
|
|
|
|
Scientific notation
|
|
|
In ColdFusion, numbers can also be represented in what is known as engineering, or scientific notation. The format of such numbers is xEy , where x is a positive real number in the range 1.0 (inclusive) to 10 (exclusive) and y is an integer number. The value of a number in the engineering notation is x times 10y, so, for example, 4.0E2 is 4.0 times 102 which is equal to 400. Similarly, 2.5E-2 is equal to 2.5 times 10-2, which is equal to 0.025. Engineering notation is very useful for writing very large and very small numbers.
|
|
|
|
Strings |
|
|
|
In ColdFusion, text values are stored in strings. Strings are pieces of text delimited on both ends by either single or double quotes. For example, the two strings below are equivalent:
"This is a string"
'This is a string'
An empty string can be written as "" (a pair of double quotes with nothing in between), or as '' (a pair of single quotes with nothing in between). Strings can have arbitrary size, limited only by the amount of available memory on the ColdFusion server.
|
|
|
|
Using quote marks and pound signs
|
|
|
Strings can use either single or double quotes. To use a single quote inside a string that is single quoted, use two single quotes. This is known as escaping the single quote:
'Single Quote: '' Double Quote: "'
To use a double quote inside a double-quoted string, use two double quotes. This is known as escaping the double quote:
"Single Quote: ' Double Quote: """
Because strings can be in either double quotes or single quotes, both of these strings are equivalent.
To insert a pound sign in a string, the pound sign must be escaped, or doubled, as in:
"This is a pound sign ##"
|
|
|
|
Boolean values |
|
|
|
Boolean values store the result of a logical operation. Thus their value can be one of truth, or falsity. ColdFusion has two special constants -- TRUE and FALSE -- for each of these values. For example:
1 IS 1 is an expression that evaluates to TRUE.
"Monkey" CONTAINS "Money" is an expression that evaluates to FALSE.
The two Boolean values can be used directly in expressions, as in:
<CFSET UserHasBeenHere=TRUE>
The numerical value of TRUE is 1. The numerical value of FALSE is 0. When converted to a string, TRUE becomes "YES" and FALSE becomes "NO".
|
|
|
|
Date-and-time values |
|
|
|
ColdFusion can perform a variety of operations on date-and-time values. Date-and-time values identify a date and time in the range 100AD to 9999AD.
There are a variety of ways in which a date-and-time value can be entered in ColdFusion. You can use the functions that create date-and-time objects using various criteria. (See the CFML Language Reference for information about date-and-time functions.)
You can also directly enter a date-and-time object in a familiar format:
"October 30, 1998"
"Oct 30, 1998"
"Oct. 30, 1998"
"10/30/98"
"1998-30-10"
|
|
|
|
21st century dates
|
|
|
Two-digit years from 00 to 29 are treated as 21st century dates; 30 to 99 are treated as 20th century dates.
"October 30, 2015"
"October 30, 15"
|
|
|
|
Time formats
|
|
|
If no time part is specified, time is set to 12:00am. Times can be added in a variety of common formats as well:
"October 30, 1998 02:34:12"
"October 30, 1998 2:34a"
"October 30, 1998 2:34am"
"October 30, 1998 02:34am"
"October 30, 1998 2am"
The time part of the object is accurate to the second.
|
|
|
|
Note
|
|
|
Internally to ColdFusion, date-and-time values are represented on a time line as a subset of the real numbers. This is done for efficiency in evaluation and because it directly mimics the method used by many popular database systems, including Microsoft Access. One day is equal to the difference between two successive integers. The time portion of the date-and-time value is stored in the fractional part of the real number.
Thus, arithmetic operations can be used to manipulate date-and-time values. For example, Now() + 1 will evaluate to tomorrow at the same time. However, we strongly discourage ColdFusion developers from using this potentially troublesome method of manipulating date-and-time objects. Date-and-time manipulation routines should be used instead.
|
|
|
|
Lists |
|
|
|
Lists are objects that enable ColdFusion developers to easily perform sophisticated manipulation operations on collections of elements returned by Web browsers and some ColdFusion functions such as ValueList, QuotedValueList.
Lists are a special kind of string. When a string is viewed as a list, all characters inside it are divided into two types--delimiters and non-delimiters. Elements of the list consist of the text between (one or more) delimiters. Elements consist entirely of non-delimiter characters. In general, the structure of a string viewed as a list can be described as:
"TextElementDelimiterTextElementTextDelimiterText..."
Here's an example of how this might look:
"Biology,Chemistry,Geology,Physics"
|
|
|
|
Examples
|
|
|
- "1,2,3" is a three-element list with "," as the delimiting character. The first element is "1", the second is "2", and the third is "3".
- "First;Second" is a two-element list with ";" as the delimiting character. The first element is "First", the second is "Second".
- "A,B;C,D" is a three-element list with "," as the delimiting character. The first element is "A", the second is "B;C", and the third is "D".
- "A,B;C,D" is a two-element list with ";" as the delimiting character. The first element is "A,B", the second is "C,D". "A,B;C,D" is a four-element list with both "," and ";" as the delimiting characters. The first element is "A", the second is "B", the third is "C," and the fourth is "D".
As the examples show, a list can have more than one delimiting character. The default delimiting character, used by all list processing functions is a comma: ",".
Elements in lists can be separated by more than one delimiter. For example, the list "1xx2xyz3" has the three elements "1", "2", and "3" as long as the delimiters include all of "x", "y", and "z".
Delimiters before the first element and after the last element will be ignored. Thus the list "1xx2xyz3" from the previous example will be processed in the same way as the list "zzy1xx2xyz3yz".
Note that the structure of lists is flat - that is, lists cannot be nested into one another. Also, lists can contain no "empty" elements. A list can be empty, however. The empty list is equivalent to the empty string "".
A word of caution: white space is not considered a delimiter. When using lists where elements may be separated by white space as well as other delimiters, be sure to add the white space characters to the delimiters. For example, "1, 2, 3" should probably be processed with both the comma and the space as delimiters.
|
|
|
|
Structures |
|
|
|
You can use structures to create and maintain key-value pairs. You can also use structures to refer to related string values as a unit rather than individually. For example, a structure lets you build a collection of related variables that are grouped under a single name. You can also use structures to create associative arrays.
You create structures by assigning a variable name to the structure with the StructNew function. For example, to create a structure named employee, use this syntax:
<CFSET employee=StructNew()>
You can add key-value pairs to the structure using the StructInsert function:
<CFSET value=StructInsert(structure_name, key, value)>
For more information about structures, see the Working with Structures chapter in this book.
|
|
|
|
Arrays |
|
|
|
Arrays are essentially tables of objects or data that can be indexed. Although the ArrayNew function only supports creating up to three-dimensional arrays, there is no limit on array size or maximum dimension. You can piece together arrays of dimension greater than three by adding arrays to array indexes.
Array objects can be created by assigning an existing array to a new variable:
<CFSET myarray2=myarray>
In this case, a separate copy of the data in myarray is copied to myarray2. Changes made in myarray are not reflected in myarray2. It is very important to understand that such assignments are very resource-intensive since the entire array is copied from one variable to the other. This operation can significantly affect performance when large arrays are involved.
Elements stored in an array are referenced as follows:
<CFSET myarray[1][2]=Now()>
For more information about arrays, see the Working with Arrays chapter in this book.
|
|
|
|
Note
|
|
|
Complex objects, such as arrays, structures, queries, and COM objects, are passed to custom tags surrounded by pound signs (#).
|
|
|
|
Queries |
|
|
|
Like arrays, ColdFusion queries can be referenced as objects by assigning a query to a variable:
<CFQUERY NAME=myquery
DATASOURCE=mydata
SELECT * FROM CUSTOMERS
</CFQUERY>
<CFSET myquery2=myquery>
In this case (unlike the same operation with arrays) the query is not copied. Instead, both names point to the record set data so that if you make changes to the table referenced in the query, the original query and the query object myquery2 will both reflect those changes.
Query columns can be referenced as if they were one-dimensional arrays using cursor-style processing. However, they are not dynamically scalable.
<CFSET myvar=queryname.columnname[index]>
Multiple queries of the same name can now be run in the same application page, so dynamic expression evaluation doesn't need to be used to run queries inside a loop. And queries can be passed as objects to custom tags.
However, queries and variables cannot have the same name at the same time in the same application page. You can make a query available to all ColdFusion applications on a specified server by assigning a query to a server variable:
<CFSET Server.query=myquery>
When you want to clear the server scope query, you reassign the query object:
<CFSET Server.query=0>
|
|
|
|
Note
|
|
|
Complex objects, such as arrays, structures, queries, and COM objects are passed to custom tags surrounded by pound signs (#).
|
|
|
|
COM objects |
|
|
|
COM (Component Object Model) objects are non-visual components that encapsulate specific functionality you can invoke in your application pages. ActiveX, OCX, CORBA, and ADO objects are examples of COM objects.
COM objects are created using CFOBJECT and CFSET (when the right-hand side of the expression evaluates to an object):
<CFOBJECT ACTION="Create"
NAME="Mailer"
CLASS=SMTP.Mailer>
<CFSET myvar=Mailer>
<CFSET MessageObj=Mailer.GetCurrentMessageObject()>
COM objects generally contain methods, like functions, you can use to execute certain operations:
<CFSET temp=Mailer.SendMail()>
COM objects also generally contain properties you can read and write using ColdFusion variables:
<CFSET Mailer.FromName=Form.fromname>
Properties can be invoked on either side of an assignment:
<!--- To set the Mailer.Subject property --->
<CFSET Mailer.Subject=form.subject>
<!--- To get the Mailer.Subject property --->
<CFSET subject=Mailer.Subject>
Methods and properties can return objects such as arrays, queries, and other COM objects.
For a COM object to be used by ColdFusion, it needs to be registered and it needs to expose the IDispatch interface. For more information about COM objects, see the Using Objects chapter in this book.
|
|
|
|
Note
|
|
|
Complex objects, such as arrays, structures, queries, and COM objects are passed to custom tags surrounded by pound signs (#).
|
|
|
|
Variables |
|
|
|
When variables are used in ColdFusion expressions, the value stored in the variable is returned. The values can be one of the previously described basic objects: numbers, strings, Boolean values, date-and-time objects, or lists.
Variable names must begin with a letter that can be followed by any number of letters, numbers, or the underscore character "_". For example, TheVariable_1 and TheVariable_2 are valid variable names, while 1stVariable and WhatAVariable! are not.
Sometimes variable names can begin with a qualifier that itself is a variable name. The qualifier name of a variable is separated from the qualified name with a period character (.). For example, Form.MyVariable is a valid qualified variable name. The qualifier, in this case "Form," signifies that we are interested in the form variable MyVariable, as opposed to, for example, the client variable MyVariable (Client.MyVariable). Qualifiers are also known as scopes. Thus MyVariable is said to belong to the Form scope.
In some cases, a variable must have pounds signs around it to allow ColdFusion to distinguish it from string or HTML text and to insert its value as opposed to its name. For more information on how to use pound signs in expressions see Using Pound Signs.
|
|
|
|
Functions
|
|
|
Because ColdFusion functions return basic objects, such as numbers, strings, Boolean values, date-and-time objects, lists, arrays, structures, queries, and COM objects, their results are basic expression terms.
|
|
|
  
|
|
|
AllaireDoc@allaire.com
Copyright © 1998, Allaire Corporation. All rights reserved.
|
|