# struct Time::Format

- Time::Format
- Struct
- Value
- Object

##
Overview

Specifies the format to convert a `Time` to and from a `String`.

The pattern of a format is a `String` with directives. Directives being with a percent (`%`) character. Any text not listed as a directive will be passed/parsed through the output/input string.

The directives are:

- %a: short day name (Sun, Mon, Tue, ...)
- %^a: short day name, upcase (SUN, MON, TUE, ...)
- %A: day name (Sunday, Monday, Tuesday, ...)
- %^A: day name, upcase (SUNDAY, MONDAY, TUESDAY, ...)
- %b: short month name (Jan, Feb, Mar, ...)
- %^b: short month name, upcase (JAN, FEB, MAR, ...)
- %B: month name (January, February, March, ...)
- %^B: month name, upcase (JANUARY, FEBRUARY, MARCH, ...)
- %c: date and time (Tue Apr 5 10:26:19 2016)
- %C: year divided by 100
- %d: day of month, zero padded (01, 02, ...)
- %-d: day of month (1, 2, ..., 31)
- %D: date (04/05/16)
- %e: day of month, blank padded (" 1", " 2", ..., "10", "11", ...)
- %F: ISO 8601 date (2016-04-05)
- %g: week-based calendar year modulo 100 (00..99)
- %G: week-based calendar year (0001..9999)
- %h: (same as %b) short month name (Jan, Feb, Mar, ...)
- %H: hour of the day, 24-hour clock, zero padded (00, 01, ..., 24)
- %I: hour of the day, 12-hour clock, zero padded (00, 01, ..., 12)
- %j: day of year, zero padded (001, 002, ..., 365)
- %k: hour of the day, 24-hour clock, blank padded (" 0", " 1", ..., "24")
- %l: hour of the day, 12-hour clock, blank padded (" 0", " 1", ..., "12")
- %L: milliseconds, zero padded (000, 001, ..., 999) (same as %3N)
- %m: month number, zero padded (01, 02, ..., 12)
- %_m: month number, blank padded (" 1", " 2", ..., "12")
- %-m: month number (1, 2, ..., 12)
- %M: minute, zero padded (00, 01, 02, ..., 59)
- %3N: milliseconds, zero padded (000, 001, ..., 999) (same as %L)
- %6N: microseconds, zero padded (000000, 000001, ..., 999999)
- %9N: nanoseconds, zero padded (000000000, 000000001, ..., 999999999)
- %N: second fraction, zero padded. (Same as `%9N` but may consume more than 9 digits while parsing)
- %p: am-pm (lowercase)
- %P: AM-PM (uppercase)
- %r: 12-hour time (03:04:05 AM)
- %R: 24-hour time (13:04)
- %s: seconds since unix epoch (see `Time#to_unix`)
- %S: seconds, zero padded (00, 01, ..., 59)
- %T: 24-hour time (13:04:05)
- %u: day of week (Monday is 1, 1..7)
- %V: ISO calendar week number of the week-based year (01..53)
- %w: day of week (Sunday is 0, 0..6)
- %x: (same as %D) date (04/05/16)
- %X: (same as %T) 24-hour time (13:04:05)
- %y: year modulo 100
- %Y: year, zero padded
- %z: time zone as hour and minute offset from UTC (+0900)
- %:z: time zone as hour and minute offset from UTC with a colon (+09:00)
- %::z: time zone as hour, minute and second offset from UTC with a colon (+09:00:00)

##
Defined in:

##
Constructors

- .new(pattern : String, location : Location? = nil)

  Creates a new `Time::Format` with the given pattern.

##
Instance Method Summary

- #format(time : Time, io : IO) : Nil

  Formats a `Time` into the given io.

- #format(time : Time) : String

  Turns a `Time` into a `String`.

- #from_json(pull : JSON::PullParser)
- #from_yaml(ctx : YAML::ParseContext, node : YAML::Nodes::Node) : Time
- #parse(string, location = @location) : Time

  Parses a string into a `Time`.

- #pattern : String

  Returns the string pattern of this format.

- #to_json(value : Time, json : JSON::Builder)
- #to_yaml(value : Time, yaml : YAML::Nodes::Builder)

### Instance methods inherited from struct `Struct`

==(other) : Bool ==, hash(hasher) hash, inspect(io : IO) : Nil inspect, pretty_print(pp) : Nil pretty_print, to_s(io : IO) : Nil to_s

### Instance methods inherited from struct `Value`

==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup

### Instance methods inherited from class `Object`

!=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, __crystal_pseudo_! : Bool __crystal_pseudo_!, __crystal_pseudo_as(type : Class) __crystal_pseudo_as, __crystal_pseudo_as?(type : Class) __crystal_pseudo_as?, __crystal_pseudo_is_a?(type : Class) : Bool __crystal_pseudo_is_a?, __crystal_pseudo_nil? : Bool __crystal_pseudo_nil?, __crystal_pseudo_responds_to?(name : Symbol) : Bool __crystal_pseudo_responds_to?, class class, dup dup, hash(hasher)
hash hash, inspect : String
inspect(io : IO) : Nil inspect, itself itself, not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, tap(&) tap, to_json(io : IO)
to_json to_json, to_pretty_json(indent : String = " ")
to_pretty_json(io : IO, indent : String = " ") to_pretty_json, to_s : String
to_s(io : IO) : Nil to_s, to_yaml(io : IO)
to_yaml to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

### Class methods inherited from class `Object`

from_json(string_or_io, root : String)
from_json(string_or_io) from_json, from_yaml(string_or_io : String | IO) from_yaml

##
Constructor Detail

def self.new(pattern : String, location : Location? = nil) #

Creates a new `Time::Format` with the given pattern. The given time location will be used when parsing a `Time` and no time zone is found in it.

##
Instance Method Detail

def format(time : Time, io : IO) : Nil #

Formats a `Time` into the given io.

def format(time : Time) : String #

Turns a `Time` into a `String`.

def from_json(pull : JSON::PullParser) #
def from_yaml(ctx : YAML::ParseContext, node : YAML::Nodes::Node) : Time #
def parse(string, location = @location) : Time #

Parses a string into a `Time`.

def pattern : String #

Returns the string pattern of this format.

def to_json(value : Time, json : JSON::Builder) #
def to_yaml(value : Time, yaml : YAML::Nodes::Builder) #