DateTimeFormatter Classe

Definição

[Android.Runtime.Register("java/time/format/DateTimeFormatter", ApiSince=26, DoNotGenerateAcw=true)]
public sealed class DateTimeFormatter : Java.Lang.Object

[<Android.Runtime.Register("java/time/format/DateTimeFormatter", ApiSince=26, DoNotGenerateAcw=true)>]
type DateTimeFormatter = class
    inherit Object

Herança

Object

JavaObject

Object

DateTimeFormatter

Atributos

RegisterAttribute

Comentários

Formatador para imprimir e analisar objetos de data e hora.

Essa classe fornece o ponto de entrada principal do aplicativo para impressão e análise e fornece implementações comuns de : ulDateTimeFormatterli Usando constantes predefinidas, como <>/li<>li#ISO_LOCAL_DATEUsando letras padrão, como<> /li li<>uuuu-MMM-ddUsando estilos localizados, como < ou ></li>long/ulmedium<><>

Os formatadores mais complexos são fornecidos por DateTimeFormatterBuilder DateTimeFormatterBuilder.

As classes de data e hora principais fornecem dois métodos : um para formatação format(DateTimeFormatter formatter)e outro para análise. parse(CharSequence text, DateTimeFormatter formatter)

Por exemplo: <blockquote>

LocalDate date = LocalDate.now();
             String text = date.format(formatter);
             LocalDate parsedDate = LocalDate.parse(text, formatter);

</blockquote>

Além do formato, os formatadores podem ser criados com Locale, Chronology, ZoneId e DecimalStyle desejados.

O #withLocale withLocale método retorna um novo formatador que substitui a localidade. A localidade afeta alguns aspectos de formatação e análise. Por exemplo, o #ofLocalizedDate ofLocalizedDate fornece um formatador que usa o formato de data específico da localidade.

O #withChronology withChronology método retorna um novo formatador que substitui a cronologia. Se substituído, o valor de data/hora será convertido na cronologia antes da formatação. Durante a análise, o valor de data e hora é convertido na cronologia antes de ser retornado.

O #withZone withZone método retorna um novo formatador que substitui a zona. Se substituído, o valor de data/hora será convertido em ZonedDateTime com a ZoneId solicitada antes da formatação. Durante a análise, o ZoneId é aplicado antes que o valor seja retornado.

O #withDecimalStyle withDecimalStyle método retorna um novo formatador que substitui o DecimalStyle. Os símbolos DecimalStyle são usados para formatação e análise.

Alguns aplicativos podem precisar usar a classe mais antiga Format java.text.Format para formatação. O #toFormat() método retorna uma implementação de java.text.Format.

<h2 id="predefined">Predefined Formatters</h2><table class="striped" style="text-align:left"><caption>Predefined Formatters</caption><thead><tr><th scope="col">Formatter</th th><scope="col">Description</th th><scope="col">Example</th></tr></thead><tbody><tr><th scope="row">#ofLocalizedDate ofLocalizedDate(dateStyle)</th><td> Formatter com estilo de data da localidade </td><td> '2011-12-03'</td></tr><tr><th scope="row">#ofLocalizedTime ofLocalizedTime(timeStyle)</th><td> Formatter with time style from the locale </td><td> '10:15:30'</td></tr><tr><th scope="row">#ofLocalizedDateTime ofLocalizedDateTime(dateTimeStyle)</th><td> Formatter with a style for date and time from the locale</td td><td> '3 Jun 2008 11:05:30'</td></tr><tr><th scope="row">#ofLocalizedDateTime ofLocalizedDateTime(dateStyle,timeStyle)</th><td> Formatter with date and time styles from the locale </td td><> '3 Jun 3 Jun 2008 11:05'</td></tr><tr><th scope="row">#BASIC_ISO_DATE</th><td>Basic ISO date </td td'20111203><>'</td></tr><tr><th scope="row" >#ISO_LOCAL_DATE</th>td< ISO Local Date >/td td'2011-12-03<><'>/td<>/tr<>tr<>th scope="row"<>#ISO_OFFSET_DATE/th<>td< ISO Date with offset >/td<>t'2011-12-03<+01:00'>/td<>/tr<>tr<>th scope="row"<>#ISO_DATE/th<>td< ISO Date with or without offset >/td<>td '<> 2011-12-03+01:00'; '2011-12-03'</td></tr><tr><th scope="row">#ISO_LOCAL_TIME</th><td> Time without offset </td td'10><>:15:30'</td></tr><tr><th scope="row">#ISO_OFFSET_TIME</th><td> Time with offset </td td'10><>:15:30+01:00'</td></tr><tr><th scope="row">/th#ISO_TIME<td> Time with or without offset </td td'10><>:15:30+01:00';<> '10:15:30'</td></tr><tr><th scope="row">#ISO_LOCAL_DATE_TIME</th><td> ISO Local Date and Time </td td'2011-12-03T10><>:15:30'</td></tr><tr><th scope="row">#ISO_OFFSET_DATE_TIME</th><td> Date Time with Offset </td td'2011-12-03T10><>:15:30+01:00'</td></tr><tr th>< scope="row">#ISO_ZONED_DATE_TIME</th><td> Zoned Date Time </td td'2011-12-03T10><>:15:30+01:00[Europa/Paris]'</td></tr><tr><th scope="row".>#ISO_DATE_TIME</th><td> Data e hora com ZoneId </td td'2011-12-03T10><>:15:30+01:00[Europa/Paris]'</td></tr><tr><th scope="row"/>#ISO_ORDINAL_DATE< th>td< Ano e dia do ano >/td td'2012-337<><'>/td<>/tr<>tr tr<>th scope="row"<>#ISO_WEEK_DATE/th<>td< Year and Week >/td td'2012-W48-6<><'>/td</tr><>tr<>th scope="row"<>#ISO_INSTANT/th<>td< Date and Time of an Instant >/td td'2011-12-03T10<><:15:30Z'></td></tr><tr><th scope="row">#RFC_1123_DATE_TIME</th><td> RFC 1123 / RFC 822 </td td'Tue><>, 3 Jun 2008 11:05:30 GMT'</td></tr></tbody></table>

<h2 id="patterns">Patterns for Formatting and Parsing</h2> Patterns are based on a simple sequence of letters and symbols. Um padrão é usado para criar um Formatador usando os métodos e #ofPattern(String) os #ofPattern(String, Locale) métodos. Por exemplo, "d MMM uuuu" formatará 2011-12-03 como '3  Dec  2011'. Um formatador criado a partir de um padrão pode ser usado quantas vezes for necessário, ele é imutável e é thread-safe.

Por exemplo: <blockquote>

LocalDate date = LocalDate.now();
             DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy MM dd");
             String text = date.format(formatter);
             LocalDate parsedDate = LocalDate.parse(text, formatter);

</blockquote>

Todas as letras 'A' a 'Z' e 'a' a 'z' são reservadas como letras padrão. As seguintes letras padrão são definidas: <table class="striped"><caption>Pattern Letters and Symbols</caption><thead><tr><th scope="col">Symbol</th th><scope="col">Meaning</th th><scope="col">Presentation</th th><scope="col">Examples</th></thead><tbody><tr><th scope="row">G</th><td>era</td><td>text</td><td>AD; Anno Domini; A</td><tr><th scope="row">u</th><td>year</td td><>year</td td><td>2004; 04</td><tr><th scope="row">y</th><td>year-of-era</td td><>year</td td><>2004; 04</td><tr><th scope="row">D</th><td>day-of-year</td><td>number</td><td>189</td><tr><th scope="row">M/L</th><td>month-of-year</td td><>number/text</td td><>7; 07; Jul; Julho; J</td><tr><th scope="row">d</th><td>day-of-month</td td><>number</td td><>10</td><tr><th scope="row">g</th><td>modified-julian-day</td><td>number</td td><>2451334</td>

<tr><th scope="row">Q/q</th><td>quarter-of-year</td td><>number/text</td td><>3; 03; Q3; 3º trimestre</td><tr><th scope="row">Y</th><td>week-based-year</td td><>year</td td><>1996; 96</td><tr><th scope="row">w</th><td>week-of-week-based-year</td td><>number</td td><>27</td><tr><th scope="row">W</th><td>week-of-month</td><td>number</td><td>4</td><tr><th scope="row">E</th><td>day-of-week</td td><>text</td td><>Tue; Terça-feira; T</td><tr><th scope="row">e/c</th><td>localized day-of-week</td td><>number/text</td td><>2; 02; Ter; Terça-feira; T</td><tr><th scope="row">F</th><td>day-of-week-in-month</td><td>number</td td><>3</td>

<tr><th scope="row">a</th><td>am-pm-of-day</td td><>text</td td><>PM</td><tr><th scope="row"h/th td clock-hour-of-am-pm (1--th scope="row">h</th><td>clock-hour-of-am-pm (1--th 12)</td td><>number</td td><>12</td><tr><th scope="row">K</th><td>hour-of-am-pm (0-11)</td td><>number</td td td 0><></td><tr><th scope="row">k</th><td>clock-hour-of-day (1-24)</td td><>number</td td><>24</td>

<tr><th scope="row">H</th><td>hour-of-day (0-23)</td><td>number</td td><td>0</td><tr><th scope="row">m</th><td>minute-of-hour</td><td>number</td td><>30</td><tr><th scope="row">s</th><td>second-of-minute</td><td>number</td td><>55</td><tr><th scope="row">S</th><td>fraction-of-second</td td><>fraction</td td><>978</td><tr><th scope="row">A</th><td>milli-of-day</td><td td>number</td><>1234</td><tr><th scope="row">n</th><td>nano-of-second</td td><>number</td><td>987654321</td><tr><th scope="row">N</th><td>nano-of-day</td td><>number</td td><>12340000000</td>

<tr><th scope="row">V</th><td>time-zone ID</td td><>zone-id</td td><>America/Los_Angeles; Z; -08:30</td><tr><th scope="row">v</th><td>generic time-zone name</td td><>zone-name</td td><>Pacific Time; PT</td><tr><th scope="row">z</th><td>time-zone name</td td><>zone-name</td td><>Pacific Standard Time; PST</td><tr><th scope="row">O</th><td>localized zone-offset</td td><>offset-O</td td><>GMT+8; GMT+08:00; UTC-08:00</td><tr><th scope="row">X</th><td>zone-offset 'Z' for zero</td><td>offset-X</td td><>Z; -08; -0830; -08:30; -083015; -08:30:15</td><tr><th scope="row">x</th><td>zone-offset</td td><>offset-x</td td><>+0000; -08; -0830; -08:30; -083015; -08:30:15</td><tr><th scope="row">Z</th><td>zone-offset</td td><>offset-Z</td td><>+0000; -0800; -08:00</td>

<tr><th scope="row">p</th><td>pad next</td td><>pad modifier</td td><td>1</td>

<tr><th scope="row">'</th><td>escape for text</td td><>delimiter</td td><></td><tr><th scope="row">'</th><td>single quote</td td><>literal</td td><>'</td><tr><th scope="row">[</th><td>optional section start</td td><></td td><></td tr><><th scope="row">]</th>td<optional section end>/td td<></td td><></td><>tr<th scope="row"><#>/th<>td<reserved for future use>/td td<></td td><></td><>tr<th scope="row"><{>/th<>td<reserved for future use>/td td<></td td><></td><>tr<th scope="row"><}>/th<>td<>reservado para uso< futuro/td td><></td></td></td></tbody></table>

A contagem de letras padrão determina o formato.

<b>Texto</b>: o estilo de texto é determinado com base no número de letras padrão usadas. Menos de 4 letras padrão usarão o TextStyle#SHORT short form. Exatamente 4 letras padrão usarão o TextStyle#FULL full form. Exatamente 5 letras padrão usarão o TextStyle#NARROW narrow form. As letras padrão 'L', 'c' e 'q' especificam a forma autônoma dos estilos de texto.

<b>Número</b>: se a contagem de letras for uma, o valor será a saída usando o número mínimo de dígitos e sem preenchimento. Caso contrário, a contagem de dígitos é usada como a largura do campo de saída, com o valor zero-preenchido conforme necessário. As letras padrão a seguir têm restrições na contagem de letras. Somente uma letra de 'c' e 'F' pode ser especificada. Até duas letras de 'd', 'H', 'h', 'K', 'k', 'm' e 's' podem ser especificadas. Até três letras de 'D' podem ser especificadas.

<b>Número/Texto</b>: se a contagem de letras padrão for 3 ou maior, use as regras de Texto acima. Caso contrário, use as regras de Número acima.

<b>Fração</b>: gera o campo nano de segundo como uma fração de segundo. O valor nano-de-segundo tem nove dígitos, portanto, a contagem de letras padrão é de 1 a 9. Se for menor que 9, o valor nano-de-segundo será truncado, com apenas os dígitos mais significativos sendo a saída.

<b>Ano</b>: a contagem de letras determina a largura mínima do campo abaixo da qual o preenchimento é usado. Se a contagem de letras for dois, um DateTimeFormatterBuilder#appendValueReduced reduced formulário de dois dígitos será usado. Para impressão, isso gera os dois dígitos da extrema direita. Para análise, isso será analisado usando o valor base de 2000, resultando em um ano dentro do intervalo de 2000 a 2099, inclusive. Se a contagem de letras for menor que quatro (mas não duas), o sinal será apenas uma saída para anos negativos de acordo SignStyle#NORMALcom . Caso contrário, o sinal será a saída se a largura do painel for excedida, de acordo SignStyle#EXCEEDS_PADcom .

<b>ZoneId</b>: isso gera a ID do fuso horário, como "Europa/Paris". Se a contagem de letras for duas, a ID do fuso horário será a saída. Qualquer outra contagem de letras IllegalArgumentExceptioné gerada.

<b>Nomes< de zona/b>: isso gera o nome de exibição da ID do fuso horário. Se a letra padrão for 'z', a saída será o nome da zona com reconhecimento de horário de verão. Se não houver informações suficientes para determinar se o DST se aplica, o nome ignorando o horário de verão será usado. Se a contagem de letras for uma, duas ou três, o nome curto será a saída. Se a contagem de letras for quatro, o nome completo será a saída. Cinco ou mais cartas são lançadas IllegalArgumentException.

Se a letra padrão for 'v', a saída fornecerá o nome da zona ignorando o horário de verão. Se a contagem de letras for uma, o nome curto será a saída. Se a contagem de letras for quatro, o nome completo será a saída. Duas, três e cinco ou mais letras são lançadas IllegalArgumentException.

<b>Deslocamento X e x</b>: formata o deslocamento com base no número de letras padrão. Uma letra exibe apenas a hora, como '+01', se o minuto não for zero, caso em que o minuto também é exibido, como '+0130'. Dois caracteres exibem a hora e o minuto, sem dois-pontos, como '+0130'. Três caracteres exibem a hora e o minuto, com dois-pontos, como '+01:30'. Quatro letras produzem a hora e o minuto e o segundo opcional, sem usar dois-pontos, como '+013015'. Cinco caracteres produzem a hora, o minuto e o segundo opcional, separados por dois-pontos, como '+01:30:15'. Seis ou mais cartas são lançadas IllegalArgumentException. A letra padrão 'X' (maiúscula) produzirá 'Z' quando o deslocamento a ser produzido for zero, enquanto a letra padrão 'x' (minúscula) produzirá '+00', '+0000' ou '+00:00'.

<b>Deslocamento O</b>: com um deslocamento diferente de zero, isso formata o deslocamento localizado com base no número de letras padrão. Uma letra gera a forma curta TextStyle#SHORT do deslocamento localizado, que é o texto de deslocamento localizado, como 'GMT', com hora sem zero à esquerda, minuto opcional de 2 dígitos e segundo, se não zero, e dois-pontos, por exemplo 'GMT+8'. Quatro letras geram o formulário completo TextStyle#FULL, que é o texto de deslocamento localizado, como 'GMT, com campo de 2 dígitos de hora e minuto, segundo campo opcional se não zero e dois-pontos, por exemplo 'GMT+08:00'. Se o deslocamento for zero, somente o texto localizado será a saída. Qualquer outra contagem de letras IllegalArgumentExceptioné gerada.

<b>Deslocamento Z</b>: formata o deslocamento com base no número de letras padrão. Uma, duas ou três letras gera a hora e o minuto, sem dois-pontos, como '+0130'. A saída será '+0000' quando o deslocamento for zero. Quatro letras geram a forma completa TextStyle#FULL de deslocamento localizado, equivalente a quatro letras de Offset-O. A saída será o texto de deslocamento localizado correspondente se o deslocamento for zero. As cinco letras geram a hora, minuto, com o segundo opcional, se for diferente de zero, com dois-pontos. Ele produz 'Z' quando o deslocamento é zero. Seis ou mais cartas são lançadas IllegalArgumentException.

<b>Seção opcional</b>: os marcadores de seção opcionais funcionam exatamente como chamada DateTimeFormatterBuilder#optionalStart() e DateTimeFormatterBuilder#optionalEnd().

<b>Modificador< de pad/b>: modifica o padrão que segue imediatamente para ser acolchoado com espaços. A largura do painel é determinada pelo número de letras padrão. Isso é o mesmo que chamar DateTimeFormatterBuilder#padNext(int).

Por exemplo, 'ppH' gera a hora do dia acolchoados à esquerda com espaços a uma largura de 2.

Qualquer carta não reconhecida é um erro. Qualquer caractere que não seja letra, diferente de '[', ']', '{', '}', '#' e a única aspa será saída diretamente. Apesar disso, é recomendável usar aspas simples em torno de todos os caracteres que você deseja produzir diretamente para garantir que as alterações futuras não interrompa seu aplicativo.

<h2 id="resolving">Resolving</h2> Parsing is implemented as a two-phase operation. Primeiro, o texto é analisado usando o layout definido pelo formatador, produzindo um Map campo para valor, um ZoneId e um Chronology. Em segundo lugar, os dados <analisados são>resolvidos</em>, validando, combinando e simplificando os vários campos em campos mais úteis.

Cinco métodos de análise são fornecidos por essa classe. Quatro delas executam as fases de análise e resolução. O quinto método executa #parseUnresolved(CharSequence, ParsePosition)apenas a primeira fase, deixando o resultado não resolvido. Como tal, é essencialmente uma operação de baixo nível.

A fase de resolução é controlada por dois parâmetros, definidos nessa classe.

É ResolverStyle uma enumeração que oferece três abordagens diferentes, rigorosas, inteligentes e brandas. A opção inteligente é o padrão. Ele pode ser definido usando #withResolverStyle(ResolverStyle).

O #withResolverFields(TemporalField...) parâmetro permite que o conjunto de campos que serão resolvidos seja filtrado antes de resolver o início. Por exemplo, se o formatador tiver analisado um ano, mês, dia do mês e dia do ano, haverá duas abordagens para resolver uma data: (ano + mês + dia do mês) e (ano + dia do ano). Os campos de resolvedor permitem que uma das duas abordagens seja selecionada. Se nenhum campo de resolvedor for definido, ambas as abordagens deverão resultar na mesma data.

Resolver campos separados para formar uma data e hora completas é um processo complexo com o comportamento distribuído em várias classes. Ele segue estas etapas: <ol><li>A cronologia é determinada. A cronologia do resultado é a cronologia que foi analisada ou, se nenhuma cronologia foi analisada, é a cronologia definida nesta classe ou, se isso for nulo, será IsoChronology. <li>Os ChronoField campos de data são resolvidos. Isso é feito usando Chronology#resolveDate(Map, ResolverStyle). A documentação sobre a resolução de campo está localizada na implementação de Chronology. <li>Os ChronoField campos de tempo são resolvidos. Isso está documentado ChronoField e é o mesmo para todas as cronologias. <li>Todos os campos que não ChronoField são processados. Isso é feito usando TemporalField#resolve(Map, TemporalAccessor, ResolverStyle). A documentação sobre a resolução de campo está localizada na implementação de TemporalField. <li>Os ChronoField campos de data e hora são resolvidos novamente. Isso permite que os campos na etapa quatro produzam ChronoField valores e que sejam processados em datas e horas. <li>A LocalTime será formado se houver pelo menos uma hora de dia disponível. Isso envolve fornecer valores padrão para minuto, segundo e fração de segundo. <li>Todos os campos não resolvidos restantes são verificados cruzadamente em relação a qualquer data e/ou hora que tenha sido resolvida. Assim, um estágio anterior seria resolvido (ano + mês + dia do mês) para uma data, e essa fase verificaria se o dia da semana era válido para a data. <li>Se um número excessivo de dias #parsedExcessDays() tiver sido analisado, ele será adicionado à data se uma data estiver disponível. <li> Se um campo de segunda base estiver presente, mas LocalTime não tiver sido analisado, o resolvedor garantirá que os valores mili, micro e nano segundo estejam disponíveis para atender ao contrato de ChronoField. Elas serão definidas como zero se estiverem ausentes. <li>Se data e hora foram analisadas e um deslocamento ou zona está presente, o campo ChronoField#INSTANT_SECONDS é criado. Se um deslocamento foi analisado, o deslocamento será combinado com o LocalDateTime para formar o instantâneo, com qualquer zona ignorada. Se um ZoneId foi analisado sem um deslocamento, a zona será combinada com o LocalDateTime para formar o instante usando as regras de ChronoLocalDateTime#atZone(ZoneId). </ol>

Adicionado em 1.8.

Java documentação para java.time.format.DateTimeFormatter.

Partes desta página são modificações baseadas no trabalho criado e compartilhado pelo Project Open Source do Open Source e usadas de acordo com os termos descritos na Creative Commons 2.5.