Skip to content

Commit

Permalink
TO_CHAR conversion function. (#930)
Browse files Browse the repository at this point in the history 
* TO_CHAR conversion function.

* Adding the TO_CHAR spec

Made conversion functions to have their own subsections, too.

* Fix typos and formatting

* Update docs/modules/sql/pages/functions-and-operators.adoc

Co-authored-by: Burak Gök <[email protected]>

---------

Co-authored-by: Burak Gök <[email protected]>
  • Loading branch information
@Serdaro @burakgok
Serdaro and burakgok authored Mar 6, 2024
1 parent f58feb1 commit 418c3f1
Showing 1 changed file with 349 additions and 2 deletions.
351 changes: 349 additions & 2 deletions docs/modules/sql/pages/functions-and-operators.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -341,8 +341,9 @@ For examples of how to use aggregate functions, see the xref:select.adoc[`SELECT
Conversion functions allow you to convert the result type of one expression to another explicit type.
.Descriptions of conversion functions
[cols="1m,2,1,1"]
=== CAST
[cols="2m,2,3,1"]
|===
| Function| Description| Example| Result
Expand All @@ -357,6 +358,352 @@ Conversion functions allow you to convert the result type of one expression to a
`2020-06-03T00:00:53.11`
|===
=== TO_CHAR
[cols="2m,2,3,1"]
|===
|TO_CHAR(expression [, format model] [, NLS parameter])
|Converts a number or date to a string.
|
`SELECT ... TO_CHAR(1210.73, '9999.9')`
`SELECT ... TO_CHAR(sysdate, 'MON DDth, YYYY')`
|
`1210.7`
`APR 6th 2023`
|===
The following are the detailed specifications for the formatting and modifiers of the `TO_CHAR` function.
.Date/Time Formatting
[cols="1,2"]
|===
|Pattern | Description
|`HH`, `HH12`
|Hours of the day (1–12)
|`HH24`
|Hours of the day (0-23)
|`MI`
|Minutes of the hour (0-59)
|`SS`
|Seconds of the minute (0-59)
|`MS`, `FF3`
|Milliseconds (0-999)
|`US`, `FF6`
|Microseconds (0-999999)
|`FF1`
|Tenth of a second (0-9)
|`FF2`
|Hundredth of a second (0-99)
|`FF4`
|Tenth of a millisecond (0-9999)
|`FF5`
|Hundredth of a millisecond (0-9999)
|`SSSS`, `SSSSS`
|Seconds past midnight (0-86399)
|`AM`, `am`, `PM`, `pm`
|Meridiem indicator (without periods)
|`A.M.`, `a.m.`, `P.M.`, `p.m.`
|Meridiem indicator (with periods)
|`Y,YYY`
|Year of the era (four or more digits) with comma
|`YYYY`
|Year of the era (four or more digits)
|`YYY`
|Last three digits of the year of the era
|`YY`
|Last two digits of the year of the era
|`Y`
|Last digit of the year of the era
|`IYYY`
|ISO 8601 week-numbering year (4 or more digits)
|`IYY`
|Last three digits of the ISO 8601 week-numbering year
|`IY`
|Last two digits of the ISO 8601 week-numbering year
|`I`
|Last digit of the ISO 8601 week-numbering year
|`BC`, `bc`, `AD`, `ad`
| Era indicator (without periods)
|`B.C.`, `b.c.`, `A.D.`, `a.d.`
| Era indicator (with periods)
|`MONTH`
|Full uppercase month name (space-padded to nine chars)
|`Month`
|Full capitalized month name (space-padded to nine chars)
|`month`
|Full lowercase month name (space-padded to nine chars)
|`MON`
|Abbreviated uppercase month name (three chars in English, localized lengths vary)
|`Mon`
|Abbreviated capitalized month name (three chars in English, localized lengths vary)
|`mon`
|Abbreviated lowercase month name (three chars in English, localized lengths vary)
|`MM`
|Month number (1–12)
|`DAY`
|Full uppercase day name (space-padded to nine chars)
|`Day`
|Full capitalized day name (space-padded to nine chars)
|`day`
|Full lowercase day name (space-padded to nine chars)
|`DY`
|Abbreviated uppercase day name (three chars in English, localized lengths vary)
|`Dy`
|Abbreviated capitalized day name (three chars in English, localized lengths vary)
|`dy`
|Abbreviated lowercase day name (three chars in English, localized lengths vary)
|`DDD`
|Day of the year (1–366)
|`IDDD`
|Day of the ISO 8601 week-numbering year (1–371; day one of the year is Monday of the first ISO week)
|`DD`
|Day of the month (1–31)
|`D`
|Day of the week, Monday (1) to Sunday (7)
|`ID`
|ISO 8601 day of the week, Monday (1) to Sunday (7)
|`W`
|Week of the month (1–5) (the first week starts on the first day of the month)
|`WW`
|Week number of the year (1–53) (the first week starts on the first day of the year)
|`IW`
|Week number of the ISO 8601 week-numbering year (1–53; the first Thursday of the year is in week one)
|`CC`
|Century of the era (two digits) (the 21st century starts on 2001-01-01)
|`J`
|Julian Date (integer days since November 24, 4714 BC at local midnight)
|`Q`
|Quarter of the year (1-4)
|`RY`
|Year of the era in uppercase Roman numerals
|`ry`
|Year of the era in lowercase Roman numerals
|`RM`
|Month number in uppercase Roman numerals (I–XII)
|`rm`
|Month number in lowercase Roman numerals (i–xii)
|`RD`
|Day of the month in uppercase Roman numerals (I–XXXI)
|`rd`
|Day of the month in lowercase Roman numerals (i–xxxi)
|`TZ`
|Uppercase time-zone abbreviation, for example, GMT, UTC
|`tz`
|Lowercase time-zone abbreviation, for example, gmt, utc
|`TZH`
|Time-zoned hours, for example, +3
|`TZM`
|Time-zones minutes (0-59)
|`OF`
|Time-zoned offset from UTC, for example, +03:00
|===
.Modifiers
[cols="1,2"]
|===
|Modifier | Description
|`FM` prefix
|Enable the fill mode (suppress padding)
|`TH` suffix
|Uppercase ordinal number suffix (English only)
|`th` suffix
|Lowercase ordinal number suffix (English only)
|===
.Numeric Formatting
[cols="1,2a"]
|===
|Pattern | Description
|`9`
|Digit position (can be dropped if insignificant)
|`0`
|Digit position (will not be dropped, even if insignificant)
|`.` (period)
|Decimal separator
|`D`
|Localized decimal separator
|`,` (comma)
|Grouping separator
|`G`
|Localized grouping separator
|`V`
|Shift specified number of digits, for example, V99 = x10^2^
|`TH`
|Uppercase ordinal suffix for the integer part (English only)
|`th`
|Lowercase ordinal suffix for the integer part (English only)
|`EEEE`
|Exponent for scientific notation, for example, E+03, x10^+03
|`eeee`
|Lowercase exponent for scientific notation, for example, e+03, x10^+03
|`RN`
|Uppercase Roman numeral for the integer part
|`rn`
|Lowercase Roman numeral for the integer part
|===
[cols="1,1,2"]
|===
|Fixed |Anchored |Description
|`BR`
|`B`
|Negative value in angle brackets
|`SG`
|`S`
|Sign
|`MI`
|`M`
|Minus sign if number is negative
|`PL`
|`P`
|Plus sign if number is non-negative
|`CR`
|`C`
|Currency symbol or ISO 4217 currency code
|===
The format string consists of the integer and fraction parts, which are split at the first decimal separator, or just after the last digit position, or the end of the
format string depending on availability. The order of processing is right to left in the integer part and left to right in the fraction part.
If the format string contains the `EEEE` or `eeee` patterns, it is said to be in the exponential form, in which no overflow is possible unless the number is
infinite. If it contains the `RN` or `rn` patterns and no digit positions, it is in the Roman form, in which there is an overflow unless the number is between 1 (inclusive) and 4000 (exclusive).
Otherwise, the format string is in the normal form, in which the number overflows only if it requires more digit positions than specified for the integer part.
In this form, the `RN` and `rn` patterns format the integer part if the absolute value of the number is less than 4000; otherwise, they switch to the overflow mode.
In an overflow:
* the digit positions print a single hash (`#`)
* the `EEEE` and `eeee` patterns print `+##` as the exponent
* the `RN` and `rn` patterns print 15 hashes
* the `TH` and `th` patterns print two spaces if the number is infinite.
+
The other patterns print what they print when there is no overflow. Note that NaN (not-a-number) is considered positive.
In the normal and exponential forms, if there is no negative sign provision and there is at
least one digit position, an `M` pattern is prepended to the integer part. Similarly,
if only one part has the `BR` and/or `B` patterns, the latest bracket in the order
of processing is inserted to the opposite part. The inferred sign is inserted so that it
encloses all non-fixed patterns in the part to which it is inserted.
Lowercase variants of patterns are also accepted. If there is no special meaning of
the lowercase variant, it has the same effect as its uppercase version.
The `FM` pattern enables _the fill mode_, which suppresses padding.
* In date formats:
** If padding is enabled, numeric fields are left-padded with zeros and textual fields are left-padded with spaces.
** The padding space is printed immediately, that is, it is not possible to float the fields to one side.
* In numeric formats:
** If padding is enabled; the `9` pattern prints a single space if it corresponds to a
leading/trailing zero, decimal/grouping separators print a single space if they are
not in between digits, the `TH` pattern prints two spaces if the number is infinite,
the `RN` pattern pads the Roman numeral to meet 15 characters, the `BR` pattern
prints two spaces if the number is non-negative, and the `MI`/`PL` patterns
print a single space if the number is non-negative/negative respectively.
** The padding space is not printed until a fixed pattern or the end of
the format string is encountered. As a result, unfixed, or anchored,
patterns float right within the extra space in the integer part and float left in the
fraction part. Digit positions and decimal/grouping separators cannot float for
obvious reasons, but they are considered "transparent" while anchoring other patterns.
** Zero-padding and space-padding are completely orthogonal, which makes it possible to
have zero-padded fractions, which are aligned at the decimal separator. However, this
requires the last digit of the fraction part to be `0` if the Postgres
convention is desired.
Consecutive unrecognized characters are interpreted as a literal. It is
also possible to specify a literal by enclosing zero or more characters within double
quotes. If the format string ends before an opening quote is paired, a closing quote is
assumed just after the last character. If a double quote is to be printed, it must be
escaped with a leading backslash. In general, escaping a character causes it to lose its
special meaning if any. In numeric formats, literals are anchored by default. To fix its
position, a literal should be prepended with an `F` pattern, for example, `F$`, `F"USD"`.
== Date and Time Functions
.Descriptions of date functions
Expand Down

0 comments on commit 418c3f1

Please sign in to comment.