Contents
If you’re trying to lose some credibility with your company’s programming, using the wrong date and time formats is a surefire way to do it. Yet, you will be surprised at just how many CF’ers tend to mix these up.
It may sound like a simple mistake, but overlooking something so trivial may lead your clients to wonder what else could go wrong. That’s why it’s important that all CIOs ensure that their development team is using the proper functions, no matter how small.
In this article, you will learn:
- Why these functions are so important for CIOs
- The ColdFusion Number Format
- The ColdFusion Date Format
- The ColdFusion Time Format
- The ColdFusion DateTime Format
What makes these functions are so important for CIOs?
These are actually some of the most important functions to get correct–especially if you are doing global business. Take a look at this date.
03/04/05
What do you see? Well, that differs enormously based on where you are from, where you are currently located in the world and how your company does business.
- In the United States, that could be read as March 4th 2005.
- In some European countries, this is actually the 3rd of April 2005.
- In Japan it will be perceived as April 5th 2003.
Therein lies the problem. This can easily be fixed by using the proper ISO (International Organization for Standardization) protocol. But can your developers comfortably provide that standard?
The time and number formats in ColdFusion can be some of the most easily confused functions due to their similarities.
So let’s break down each function and clarify the differences.
1. ColdFusion NumberFormat
The NumberFormat function creates a custom formatted number value. This particular function supports the US standard for numbering. However, if you are looking to get into International numbering systems, you can use a separate function — the LSNumberFormat.
The NumberFormat can also be used to return special formats depending on one of two conditions.
-
If no mask is specified, an integer with a thousands counter is returned.
-
If the parameter value is an empty string, a zero digit can be returned.
There are two major parameters to the NumberFormat function:
The number and the mask. The number is just the number to be used. The mask, on the other hand, defines special characteristics about the number.
This table represents the Mask Characters that may be used with this function.
NumberFormat Masks and Meanings
| Mask Character | Meaning |
| + | This puts a plus sign in front of positive numbers and a minus sign in front of negative numbers. |
| – | This places a space in front of positive numbers and a minus sign in front of negative numbers |
| . | This is a mandatory decimal point. |
| 0 | This places a “0” character to the left or right of a mandatory decimal point. |
| , | This separates every third decimal place with a comma. (i.e. 100,000) |
| $ | This places a dollar sign in front of the formatted number. This must be placed first in the mask in order for this to be. |
| L, C | These characters dictate the alignment of the formatted number. “L” is for left alignment and “C” is for center alignment. There is no special character for right alignment as it is the default alignment. |
| ^ | This separates left and right formatting. |
| () | These are used when the number is less than zero. Puts parentheses around the mask. |
| _ (Underscore) | This is an optional character to be used as a placeholder. |
| 9 | This is another optional placeholder. |
The NumberFormat uses Java standard locale formatting rules on all platforms. The position of symbols in format masks determines where the codes take effect.
2. ColdFusion DateFormat
The DateFormat function provides a custom formatted date value. These dates are in US standard formats. Those looking to use international standards can use the LSDateFormat. This function is best-served formatting output instead of input. Use the CreateDate function for input.
This function will return a standard format of dd-mmm-yy unless otherwise specified in the mask of the function.
The DateFormat also has two parameters, the date and the mask.
3. DateFormat Masks and Meanings
| d | Day of the month as digits; no leading zero for single-digit days. | k/K | Hour of the day. |
| dd | Day of the month as digits; leading zero for single-digit days. | w | Week of the month. |
| ddd | Day of the week as a three-letter abbreviation. | W | Week of the year. |
| dddd | Day of the week as its full name. | w | Week of the year as digit. |
| eee/EEE | Day of the week as a three-letter abbreviation. | ww | Week of the year as digits. Leading zero for single-digit week. |
| eeee/EEEE | Day of the week as its full name. | W | Week of the month as digit. |
| f/F | Day of a week in a month. | WW | Week of the month as digits. Leading zero for single-digit week. |
| m | Month as digits; no leading zero for single-digit months. | Y | Week of the year. |
| mm | Month as digits; leading zero for single-digit months. | YY | Week of the year as last two digits; leading zero for years less than 10. |
| mmm | Month as a three-letter abbreviation. | yy | Year as last two digits; leading zero for years less than 10. |
| mmmm | Month as its full name. | yyyy/YYYY | Year represented by four digits. |
| M | Month in year. | gg | Period/era string. Ignored. Reserved. |
| D | Day in year. | short | Equivalent to m/d/y |
| medium | Equivalent to mmm d, yyyy | long | Equivalent to mmmm d, yyyy |
| full | Equivalent to dddd, mmmm d, yyyy | X | Time zone in hours of offset in ISO 8601 format.
X: +05 XX: +0530 XXX: +5:30 |
| z | Time zone in literal format. | Z | Time zone in hours of offset (RFC 822 TimeZone). |
Remember, date and time values from query results may vary significantly in format unless you use functions to format them to a standard. Use the LSDate and LSTime functions in coordination with this function to format resultset values.
4. ColdFusion TimeFormat
TimeFormat is the basic time-formatting function offered by ColdFusion. It is based on US Standard conventions. Those looking to express International time conventions should use the LSTimeFormat function.
As with the previous functions, the TimeFormat function has two parameters. The time and the masks.
5. TimeFormat Masks and Meanings
| h | Hours; no leading zero for single-digit hours (12-hour clock). | L or l | Milliseconds, with no leading zeros. |
| hh | Hours; leading zero for single-digit hours (12-hour clock). | t | One-character time marker string, such as A or P. |
| H | Hours; no leading zero for single-digit hours (24-hour clock). | tt | Multiple-character time marker string, such as AM or PM. |
| HH | Hours; leading zero for single-digit hours (24-hour clock). | short | Equivalent to h:mm tt. |
| n | Minutes; no leading zero for single-digit minutes. | medium | Equivalent to h:mm:ss tt. |
| nn | Minutes; a leading zero for single-digit minutes. | long | Medium followed by three-letter time zone; as in, 3:42:16 PM EST. |
| s | Seconds; no leading zero for single-digit seconds. | full | Same as long. |
| ss | Seconds; leading zero for single-digit seconds. | z | Time zone in literal format, for example, GMT. |
| k | Hour in day (1-24). | Z | Time zone in hours of offset (RFC 822 TimeZone), for example, +0730. |
| K | Hour in AM/PM (0-11). | X | Time zone in hours of offset in ISO 8601 format. The following are the three ways of using ‘X':
|
When using this function, it is imperative that you enclose the string within quotation marks. Failing to do so will interpret the function not as a string but as a Date/Time Object.
6. ColdFusion DateTime Format
This function formats both date and time values collectively as per Date and Time Standards. The parameters are the date, the masks, and the timezone.
This uses the same masks as both the Date and Time functions.
Here is an example from Adobe on how the DateTimeFormat function should be written and executed:
<cfscript> Date1 = "{ts '2018-11-05 12:13:50'}"; DateTimeFormat= DateTimeFormat(Date1,"m") DateTimeFormat1= DateTimeFormat(Date1,"mm") DateTimeFormat2= DateTimeFormat(Date1,"mmm") DateTimeFormat3= DateTimeFormat(Date1,"mmmm") DateTimeFormat4= DateTimeFormat(Date1,"M") writeOutput("Month as digits; no leading zero for single-digit months: " & DateTimeFormat & "") writeOutput("Month as digits; leading zero for single-digit months: " & DateTimeFormat1 & "") writeOutput(" Month as a three-letter abbreviation.: " & DateTimeFormat2 & "") writeOutput(" Month as a three-letter abbreviation.: " & DateTimeFormat3 & "") writeOutput(" Month in year: " & DateTimeFormat4 & "") </cfscript>
As you can see, these formats and functions are not particularly difficult. However, these are often mixed up due to their striking similarities. And well, that’s not good.
It would be terrible if you missed a key event due to a misformatted date or time. That’s a rather embarrassing mistake that devalues the credibility of your organization. Make sure that both you and your team are well-versed in these functions.
Have you ever heard of a date/time mishap leading to disaster? What do you do in your workplace to ensure these mistakes don’t get made?
Let us know in the comments below. We’re always down for a good story and some learned life experience. Also,if you like what you see, you can always follow us on Twitter @CFTeraTech and make sure you don’t miss an update.
Cheers!
And to continue learning how to make your ColdFusion apps more modern and alive, I encourage you to download our free ColdFusion Alive Best Practices Checklist.
Because… perhaps you are responsible for a mission-critical or revenue-generating CF application that you don’t trust 100%, where implementing new features is a painful ad-hoc process with slow turnaround even for simple requests.
What if you have no contingency plan for a sudden developer departure or a server outage? Perhaps every time a new freelancer works on your site, something breaks. Or your application availability, security, and reliability are poor.
And if you are depending on ColdFusion for your job, then you can’t afford to let your CF development methods die on the vine.
You’re making a high-stakes bet that everything is going to be OK using the same old app creation ways in that one language — forever.
All it would take is for your fellow CF developer to quit or for your CIO to decide to leave the (falsely) perceived sinking ship of CFML and you could lose everything—your project, your hard-won CF skills, and possibly even your job.
Luckily, there are a number of simple, logical steps you can take now to protect yourself from these obvious risks.
No Brainer ColdFusion Best Practices to Ensure You Thrive No Matter What Happens Next
ColdFusion Alive Best Practices Checklist
Modern ColdFusion development best practices that reduce stress, inefficiency, project lifecycle costs while simultaneously increasing project velocity and innovation.
√ Easily create a consistent server architecture across development, testing, and production
√ A modern test environment to prevent bugs from spreading
√ Automated continuous integration tools that work well with CF
√ A portable development environment baked into your codebase… for free!
Learn about these and many more strategies in our free ColdFusion Alive Best Practices Checklist.
