# CTIME Formatting

### Overview

CTIME formatting provides a way to format timestamps using directives similar to the Unix `strftime` function. This guide explains how to use CTIME format strings with practical examples.

### Basic Concept

CTIME formatting works by replacing format directives (special character sequences starting with `%`) with their corresponding components from a date/time value. For example:

* `%Y` represents the full 4-digit year
* `%m` represents the month (zero-padded)
* `%d` represents the day of month (zero-padded)

### Common Timestamp Format Examples

#### ISO 8601 Format

```
Format:  %F %T
Example: 2025-12-23 14:30:45
```

Equivalent to: `%Y-%m-%d %H:%M:%S`

#### US Short Date Format

```
Format:  %m/%d/%y
Example: 12/23/25
```

Same as the `%D` or `%x` directive

#### Full Date and Time

```
Format:  %c
Example: Mon Dec 23 14:30:45 2025
```

Complete date and time representation

#### 12-Hour Time with AM/PM

```
Format:  %I:%M:%S %p
Example: 02:30:45 PM
```

#### 24-Hour Time Only

```
Format:  %R
Example: 14:30
```

Equivalent to: `%H:%M`

#### For 24-hour time with seconds:

```
Format:  %T
Example: 14:30:45
```

Equivalent to: `%H:%M:%S`

#### RFC 2822 Style

```
Format:  %a, %b %d %Y %H:%M:%S %z
Example: Mon, Dec 23 2025 14:30:45 -0700
```

#### Log Timestamp Format

```
Format:  %Y-%m-%d %H:%M:%S.%L
Example: 2025-12-23 14:30:45.999
```

#### Verbose Format

```
Format:  %A, %B %d, %Y at %I:%M %p
Example: Monday, December 23, 2025 at 02:30 PM
```

### Directive Reference

#### Year

| Directive | Description                   | Example |
| --------- | ----------------------------- | ------- |
| `%Y`      | Year, zero-padded (0001-9999) | 2025    |
| `%y`      | Year, last two digits         | 25      |

#### Month

| Directive  | Description               | Example  |
| ---------- | ------------------------- | -------- |
| `%m`       | Month as decimal (01-12)  | 12       |
| `%o`       | Month space-padded (1-12) | 12       |
| `%q`       | Month unpadded (1-12)     | 12       |
| `%B`       | Full month name           | December |
| `%b`, `%h` | Abbreviated month         | Dec      |

#### Day of Month

| Directive | Description             | Example |
| --------- | ----------------------- | ------- |
| `%d`      | Day zero-padded (01-31) | 23      |
| `%e`      | Day space-padded (1-31) | 23      |
| `%g`      | Day unpadded (1-31)     | 23      |

#### Weekday

| Directive | Description         | Example |
| --------- | ------------------- | ------- |
| `%A`      | Full weekday name   | Monday  |
| `%a`      | Abbreviated weekday | Mon     |

#### Hour (24-hour clock)

| Directive | Description              | Example |
| --------- | ------------------------ | ------- |
| `%H`      | Hour zero-padded (00-23) | 14      |

#### Hour (12-hour clock)

| Directive | Description              | Example |
| --------- | ------------------------ | ------- |
| `%I`      | Hour zero-padded (01-12) | 02      |
| `%l`      | Hour unpadded (0-12)     | 2       |
| `%p`      | Locale AM/PM             | PM      |
| `%P`      | Locale am/pm             | pm      |

#### Minute

| Directive | Description                | Example |
| --------- | -------------------------- | ------- |
| `%M`      | Minute zero-padded (00-59) | 30      |

#### Second

| Directive | Description                | Example |
| --------- | -------------------------- | ------- |
| `%S`      | Second zero-padded (00-59) | 45      |

#### Fractional Seconds

| Directive | Description                      | Example   |
| --------- | -------------------------------- | --------- |
| `%L`      | Millisecond (000-999)            | 500       |
| `%f`      | Microsecond (000000-999999)      | 500000    |
| `%s`      | Nanosecond (000000000-999999999) | 500000000 |

#### Timezone

| Directive | Description                       | Example   |
| --------- | --------------------------------- | --------- |
| `%Z`      | Timezone name/abbreviation        | MST       |
| `%z`      | UTC offset (±HHMM\[SS\[.ffffff]]) | -0700     |
| `%w`      | UTC offset with seconds           | -070000   |
| `%i`      | UTC offset (short form)           | -07       |
| `%j`      | UTC offset with colons            | -07:00    |
| `%k`      | UTC offset full format            | -07:00:00 |

#### Composite Formats

| Directive  | Description                | Equivalent               |
| ---------- | -------------------------- | ------------------------ |
| `%D`, `%x` | Short date (MM/DD/YY)      | %m/%d/%y                 |
| `%F`       | ISO 8601 date (YYYY-MM-DD) | %Y-%m-%d                 |
| `%T`, `%X` | ISO 8601 time (HH:MM:SS)   | %H:%M:%S                 |
| `%R`       | 24-hour time (HH:MM)       | %H:%M                    |
| `%r`       | 12-hour time with AM/PM    | HH:MM:SS am/pm           |
| `%c`       | Full date and time         | Mon Jan 02 15:04:05 2006 |

#### Special Characters

| Directive | Description              |
| --------- | ------------------------ |
| `%n`      | Newline character        |
| `%t`      | Horizontal tab character |
| `%%`      | Literal % sign           |

### Practical Usage Tips

1. **Combining Directives**: You can mix multiple directives in a single format string

   ```
   %Y-%m-%d %H:%M:%S   →   2025-12-23 14:30:45
   ```
2. **Padding Variations**: Different directives provide different padding options for the same component

   ```
   %m  →  12 (zero-padded)
   %o  →  12 (space-padded)
   %q  →  12 (unpadded)
   ```
3. **Timezone Information**: Include timezone data for complete timestamp information

   ```
   %Y-%m-%d %H:%M:%S %Z   →   2025-12-23 14:30:45 MST
   ```
4. **Readable Formats**: Use full month and weekday names for human-readable timestamps

   ```
   %A, %B %d %Y   →   Monday, December 23 2025
   ```
5. **Millisecond Precision**: Include `%L` for application logs

   ```
   %Y-%m-%d %H:%M:%S.%L   →   2025-12-23 14:30:45.500
   ```

### Example Use Cases

#### Server Log Entry

```
[%Y-%m-%d %H:%M:%S.%L] User login: admin
→ [2025-12-23 14:30:45.500] User login: admin
```

#### API Response Timestamp

```
{
  "timestamp": "%FT%T%z",
  "event": "order_placed"
}
→ "timestamp": "2025-12-23T14:30:45-0700"
```

#### Email Header Format

```
Date: %a, %d %b %Y %H:%M:%S %z
→ Date: Mon, 23 Dec 2025 14:30:45 -0700
```

#### Database Audit Log

```
%Y-%m-%d %H:%M:%S | %A | Action: UPDATE
→ 2025-12-23 14:30:45 | Monday | Action: UPDATE
```

#### User-Friendly Display

```
"Last updated: %A at %I:%M %p"
→ "Last updated: Monday at 02:30 PM"
```