Movatterモバイル変換

Table 9.23. Formatting Functions

Note

There is also a single-argumentto_timestamp function; seeTable 9.30.

Table 9.24. Template Patterns for Date/Time Formatting

Table 9.25. Template Pattern Modifiers for Date/Time Formatting

• FM suppresses leading zeroes and trailing blanks that would otherwise be added to make the output of a pattern be fixed-width. InPostgreSQL,FM modifies only the next specification, while in OracleFM affects all subsequent specifications, and repeatedFM modifiers toggle fill mode on and off.

• TM does not include trailing blanks.to_timestamp andto_date ignore theTM modifier.

• to_timestamp andto_date skip multiple blank spaces in the input string unless theFX option is used. For example,to_timestamp('2000    JUN', 'YYYY MON') works, butto_timestamp('2000    JUN', 'FXYYYY MON') returns an error becauseto_timestamp expects one space only.FX must be specified as the first item in the template.

• to_timestamp andto_date exist to handle input formats that cannot be converted by simple casting. These functions interpret input liberally, with minimal error checking. While they produce valid output, the conversion can yield unexpected results. For example, input to these functions is not restricted by normal ranges, thusto_date('20096040','YYYYMMDD') returns2014-01-17 rather than causing an error. Casting does not have this behavior.

• Ordinary text is allowed into_char templates and will be output literally. You can put a substring in double quotes to force it to be interpreted as literal text even if it contains pattern key words. For example, in'"Hello Year "YYYY', theYYYY will be replaced by the year data, but the singleY inYear will not be. Into_date,to_number, andto_timestamp, double-quoted strings skip the number of input characters contained in the string, e.g.,"XX" skips two input characters.

• If you want to have a double quote in the output you must precede it with a backslash, for example'\"YYYY Month\"'.

• If the year format specification is less than four digits, e.g.,YYY, and the supplied year is less than four digits, the year will be adjusted to be nearest to the year 2020, e.g.,95 becomes 1995.

• Into_timestamp andto_date, negative years are treated as signifying BC. If you write both a negative year and an explicitBC field, you get AD again. An input of year zero is treated as 1 BC.

• Into_timestamp andto_date, theYYYY conversion has a restriction when processing years with more than 4 digits. You must use some non-digit character or template afterYYYY, otherwise the year is always interpreted as 4 digits. For example (with the year 20000):to_date('200001131', 'YYYYMMDD') will be interpreted as a 4-digit year; instead use a non-digit separator after the year, liketo_date('20000-1131', 'YYYY-MMDD') orto_date('20000Nov31', 'YYYYMonDD').

• In conversions from string totimestamp ordate, theCC (century) field is ignored if there is aYYY,YYYY orY,YYY field. IfCC is used withYY orY then the year is computed as the year in the specified century. If the century is specified but the year is not, the first year of the century is assumed.

• An ISO 8601 week-numbering date (as distinct from a Gregorian date) can be specified toto_timestamp andto_date in one of two ways:

  • Year, week number, and weekday: for exampleto_date('2006-42-4', 'IYYY-IW-ID') returns the date2006-10-19. If you omit the weekday it is assumed to be 1 (Monday).

  • Year and day of year: for exampleto_date('2006-291', 'IYYY-IDDD') also returns2006-10-19.

  Attempting to enter a date using a mixture of ISO 8601 week-numbering fields and Gregorian date fields is nonsensical, and will cause an error. In the context of an ISO 8601 week-numbering year, the concept of a“month” or“day of month” has no meaning. In the context of a Gregorian year, the ISO week has no meaning.

  Caution

  Whileto_date will reject a mixture of Gregorian and ISO week-numbering date fields,to_char will not, since output format specifications likeYYYY-MM-DD (IYYY-IDDD) can be useful. But avoid writing something likeIYYY-MM-DD; that would yield surprising results near the start of the year. (SeeSection 9.9.1 for more information.)

• In a conversion from string totimestamp, millisecond (MS) or microsecond (US) values are used as the seconds digits after the decimal point. For exampleto_timestamp('12:3', 'SS:MS') is not 3 milliseconds, but 300, because the conversion counts it as 12 + 0.3 seconds. This means for the formatSS:MS, the input values12:3,12:30, and12:300 specify the same number of milliseconds. To get three milliseconds, one must use12:003, which the conversion counts as 12 + 0.003 = 12.003 seconds.

  Here is a more complex example:to_timestamp('15:12:02.020.001230', 'HH24:MI:SS.MS.US') is 15 hours, 12 minutes, and 2 seconds + 20 milliseconds + 1230 microseconds = 2.021230 seconds.

• to_char(..., 'ID')'s day of the week numbering matches theextract(isodow from ...) function, butto_char(..., 'D')'s does not matchextract(dow from ...)'s day numbering.

• to_char(interval) formatsHH andHH12 as shown on a 12-hour clock, i.e., zero hours and 36 hours output as12, whileHH24 outputs the full hour value, which can exceed 23 for intervals.

Table 9.26. Template Patterns for Numeric Formatting

• 0 specifies a digit position that will always be printed, even if it contains a leading/trailing zero.9 also specifies a digit position, but if it is a leading zero then it will be replaced by a space, while if it is a trailing zero and fill mode is specified then it will be deleted. (Forto_number(), these two pattern characters are equivalent.)

• The pattern charactersS,L,D, andG represent the sign, currency symbol, decimal point, and thousands separator characters defined by the current locale (seelc_monetary andlc_numeric). The pattern characters period and comma represent those exact characters, with the meanings of decimal point and thousands separator, regardless of locale.

• If no explicit provision is made for a sign into_char()'s pattern, one column will be reserved for the sign, and it will be anchored to (appear just left of) the number. IfS appears just left of some9's, it will likewise be anchored to the number.

• A sign formatted usingSG,PL, orMI is not anchored to the number; for example,to_char(-12, 'MI9999') produces'-  12' butto_char(-12, 'S9999') produces'  -12'. (The Oracle implementation does not allow the use ofMI before9, but rather requires that9 precedeMI.)

• TH does not convert values less than zero and does not convert fractional numbers.

• PL,SG, andTH arePostgreSQL extensions.

• V withto_char multiplies the input values by10^n, wheren is the number of digits followingV.V withto_number divides in a similar manner.to_char andto_number do not support the use ofV combined with a decimal point (e.g.,99.9V99 is not allowed).

• EEEE (scientific notation) cannot be used in combination with any of the other formatting patterns or modifiers other than digit and decimal point patterns, and must be at the end of the format string (e.g.,9.99EEEE is a valid pattern).

Table 9.27. Template Pattern Modifiers for Numeric Formatting

Table 9.28. to_char Examples