The strftime function is a common way for programmers to convert a computer time into a human-readable string. You can pronounce it “string-f-time”, “string-from-time”, or “string-format-time”. While Ruby and PHP each have their own implementation, the function is actually part of the Unix open spec. That’s great news for developers because it means that we can reuse the formatting techniques in any language. I’ve also found that the Ruby/Rails docs are a little lacking and you might not have known that there were more options available. Since it’s not just for Ruby, we don’t have to rely on them as our sole source of information.

Keep reading and I’ll show you how to use strftime, give you a full list of format codes (downloadable even), and demonstrate a useful helper function for working around one of the quirks of strftime.

Unix timestamp

When we talk about “time”, we are actually talking about the date and time, not just the time of day. Time is stored internally as the number of seconds (and microseconds) since the Unix Epoch started on January 1, 1970 00:00 UTC. UTC stands for Universal Time Coordinated and is basically the same as GMT or Greenwich Mean Time. This count of seconds is called the Unix timestamp. (Something to keep in mind: due to technical reasons, some computers and databases act a little funky with dates before January 1, 1970 and after January 19, 2038.)

How to Use strftime

The strftime function takes a time expressed as a Unix timestamp and uses a format string to determine how it should output the time as a more readable version. The format string consists of formatting codes and ordinary characters. All ordinary characters are output as-is. Formatting codes consist of a percent sign (%) plus one character. Each code gives a format instruction. We’ll look at all the codes in a second, but first, here’s an example of a format string to illustrate how ordinary characters and codes can be mixed together.

Easy enough, right? Everything with a % is a code that gets replaced by some part of the time. For example, %y will output the last two digits of the year in the final string. Every other character in the format string (those without the %) passes through unchanged. You can pull a time from a database, use form data to assemble it, or add or subtract from the current time to get it. Then when you are ready to output the results to the browser, strftime is all you need to make it look nice. The only thing missing is a list of the formatting codes so that we can customize the date and time to look exactly like we want.

Formatting Codes

The listings for strftime on Ruby Central and in the Ruby on Rails Core Library list most but not all of the possibilities. The strftime documentation on PHP.net is better and the Open Group’s Unix spec is probably the most authoritative. Because it’s Unix, it is handy to remember that you can just pop open a Unix or Linux command line and type ‘man strftime’ to get a quick format code refresher.

At the bottom of this post is a table that I put together which has all of the formatting codes. I’ve sorted them into categories based on year, month, day, etc. I find it easier to reference this way. The online listings previously mentioned will have it alphabetically by code. I’ve also put the same formating code list into a handy reference PDF that you can download.

Some Quirks to Work Through

Either download the PDF or jump to the bottom of this post, review the codes, then come back here. There are a couple of problems I want to point out to you. Find %m, %e, and %l. Notice that %m outputs the month as a number, but there’s not an option like %e and %l which will display the month with no leading 0. January can be formated as ‘01′ but not ‘1′. And %e and %l take the liberty of adding a space in place of the zero. (And %e and %l are notable omissions from the Ruby on Rails documentation.) Because it took me awhile to look past the Rails docs and to realize that the underlying strftime function is univeral Unix, I wrote up a function in Rails that would remove leading zeros. Even after I found out that I could use %e and %l, my function still proved to be useful for getting around the other problems. I hope it will help you too.

What I needed was a way to find the extra zeros before a single-digit month or day name and remove them (instead of putting in a space). My solution was to include a special character in the format string right before the possible zero. It can be any character as long as it is not likely to be in your output string, but I picked as asterisk. When I apply my function to the strftime output, it first removes any occurrence of ‘*0′. Then it removes any remaining asterisks, because those are in front of other numbers we want to leave unchanged.

It’s a hack but it solves both problems of strftime. I get a string with no leading zeros and also without spaces in place of the zeros. I put it into ApplicationHelper and then I can call it from any view. You could do the same thing in PHP.

I haven’t needed this technique for anything besides removing those pesky zeros, but you could easily “tag” any part of the format string and then search for the tag and modify it to suit your purposes. (Maybe swap in HTML tags or do something with Textile markup.) I also see that it could be made more flexible by allowing users to specify the “tag” character in the function parameters but use the astrisk as a default. But I’ll leave further improvements up to you.

strftime Format Codes

This entry was posted on Wednesday, May 16th, 2007 at 11:20 am and is filed under PHP, Ruby on Rails, Tutorials, Unix/Linux. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.