# 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.

ASCII whitespaces in the pattern string are written verbatim when formatting, and consume any number of ASCII whitespace characters on parsing.

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: same as the newline character (`\n`)
- %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: same as the tab character (`\t`)
- %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 offset from UTC as hour and minute with no separator (+0900)
- %:z: time zone offset from UTC as hour and minute separated by colon (+09:00)
- %::z: time zone offset from UTC as hour, minute and second separated by colon (+09:00:00)
- %Z: location name or offset (e.g. `Europe/Berlin`)
- %^Z: abbreviated time zone identifier or offset (e.g. `CET`)

##
Defined in:

json/from_json.cr
json/to_json.cr
time/format.cr
time/format/custom/http_date.cr
time/format/custom/iso_8601.cr
time/format/custom/rfc_2822.cr
time/format/custom/rfc_3339.cr
time/format/custom/yaml_date.cr
time/format/formatter.cr
time/format/parser.cr
time/format/pattern.cr
yaml/from_yaml.cr
yaml/to_yaml.cr

##
Constructors

- .new(pattern : String, location : Location | Nil = 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) : Time
- #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) : Nil
- #to_yaml(value : Time, yaml : YAML::Nodes::Builder) : Nil

### 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

### Class methods inherited from struct `Struct`

pre_initialize(address : Pointer) : Nil pre_initialize

### Instance methods inherited from struct `Value`

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

### Instance methods inherited from class `Object`

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(collection : Object) : Bool
in?(*values : Object) : Bool in?, inspect(io : IO) : Nil
inspect : String inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String to_json, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil to_pretty_json, to_s(io : IO) : Nil
to_s : String to_s, to_yaml(io : IO) : Nil
to_yaml : String 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

### Macros inherited from class `Object`

class_getter(*names, &block) class_getter, class_getter!(*names) class_getter!, class_getter?(*names, &block) class_getter?, class_property(*names, &block) class_property, class_property!(*names) class_property!, class_property?(*names, &block) class_property?, class_setter(*names) class_setter, def_clone def_clone, def_equals(*fields) def_equals, def_equals_and_hash(*fields) def_equals_and_hash, def_hash(*fields) def_hash, delegate(*methods, to object) delegate, forward_missing_to(delegate) forward_missing_to, getter(*names, &block) getter, getter!(*names) getter!, getter?(*names, &block) getter?, property(*names, &block) property, property!(*names) property!, property?(*names, &block) property?, setter(*names) setter

##
Constructor Detail

def self.new(pattern : String, location : Location | Nil = 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) : Time #
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) : Nil #
def to_yaml(value : Time, yaml : YAML::Nodes::Builder) : Nil #