#types - Common Types and Utilities

#Overview

#Sub-Packages

• types/fpath: File path manipulation and validation

#Features

• Compression Enum: Type-safe compression method representation
• POSIX Time: Unix timestamp handling with DOS time conversion
• File Paths: Unix-style path utilities (via fpath sub-package)

#API

#Compression

#pub enum Compression

pub enum Compression {
  Stored    // No compression (method 0)
  Deflate   // DEFLATE compression (method 8)
  // Future: Bzip2, LZMA, etc.
} derive(Eq, Show)

#Functions

pub fn Compression::from_int(method : Int) -> Compression
pub fn Compression::to_int(self : Compression) -> Int

• 0 = Stored (no compression)
• 8 = DEFLATE

#POSIX Time (Ptime)

#pub typealias Int64 as Ptime

#Constants

pub let dos_epoch : Ptime  // 1980-01-01 00:00:00 UTC

#Functions

#ptime_to_date_time(ptime : Ptime) -> ((Int, Int, Int), (Int, Int, Int))

#ptime_of_dos_date_time(dos_date : Int, dos_time : Int) -> Ptime

• Date: (year-1980) << 9 | month << 5 | day
• Time: hour << 11 | minute << 5 | (second / 2)

#ptime_to_dos_date_time(ptime : Ptime) -> (Int, Int)

#ptime_format(ptime : Ptime) -> String

#File Paths (Fpath)

#pub typealias String as Fpath

#Functions

pub fn fpath_ensure_unix(path : Fpath) -> Fpath

pub fn fpath_ensure_directoryness(path : Fpath) -> Fpath

pub fn fpath_sanitize(path : Fpath) -> Fpath

#Usage Examples

#Compression Types

///|
test {
  // Create from ZIP method code
  let compression = @types.Compression::from_int(8) // DEFLATE

  // Convert to method code
  let method_code = compression.to_int()
  @json.inspect(method_code, content=8)

  // Test stored compression
  let stored = @types.Compression::from_int(0)
  @json.inspect(stored.to_int(), content=0)
}

#Time Conversion

// Get current time as POSIX timestamp
let now : Ptime = current_time()

// Convert to DOS format for ZIP
let (dos_date, dos_time) = ptime_to_dos_date_time(now)

// Store in ZIP file...

// Later, read from ZIP
let mtime = ptime_of_dos_date_time(dos_date, dos_time)
println("Modified: \{ptime_format(mtime)}")
// Output: "Modified: 2025-10-02 14:30:45"

#Date/Time Components

let ((year, month, day), (hour, minute, second)) = ptime_to_date_time(now)
println("\{year}-\{month}-\{day} \{hour}:\{minute}:\{second}")

#File Paths

// Normalize Windows path
let path = fpath_ensure_unix("dir\\subdir\\file.txt")
// Result: "dir/subdir/file.txt"

// Ensure directory
let dir = fpath_ensure_directoryness("mydir")
// Result: "mydir/"

// Sanitize path
let clean = fpath_sanitize("dir//subdir/./file.txt")
// Result: "dir/subdir/file.txt"

#DOS Date/Time Format

#Date Format (16 bits)

Bits 15-9: Year (0 = 1980, 127 = 2107)
Bits 8-5:  Month (1-12)
Bits 4-0:  Day (1-31)

#Time Format (16 bits)

Bits 15-11: Hour (0-23)
Bits 10-5:  Minute (0-59)
Bits 4-0:   Second / 2 (0-29, representing 0-58 seconds)

#Example

// October 2, 2025, 14:30:45
// DOS Date: (2025-1980) << 9 | 10 << 5 | 2 = 0x5A82
// DOS Time: 14 << 11 | 30 << 5 | (45/2) = 0x73D6

let dos_date = 0x5A82
let dos_time = 0x73D6
let ptime = ptime_of_dos_date_time(dos_date, dos_time)
println(ptime_format(ptime))
// Output: "2025-10-02 14:30:44" (45 seconds rounded down to 44)

#Time Range Limitations

#DOS Epoch

• Minimum: 1980-01-01 00:00:00
• Maximum: 2107-12-31 23:59:58

#ZIP File Behavior

• Times before 1980 are clamped to DOS epoch
• Times after 2107 are clamped to max DOS time
• 2-second resolution (odd seconds rounded down)

#Implementation Notes

#Compression

• Extensible enum for future compression methods
• Type-safe method codes
• Easy to add new methods (Bzip2, LZMA, etc.)

#Time Handling

• All internal times are POSIX timestamps (Int64)
• DOS conversion only at ZIP I/O boundaries
• Timezone-agnostic (UTC assumed)
• Leap second handling: not supported (matches DOS/ZIP spec)

#File Paths

• All paths normalized to Unix-style (/ separator)
• Directory paths always end with /
• Relative paths supported
• No validation of path legality (allows any string)

#Testing

moon test types

• Compression type conversion
• DOS time conversion (boundary cases)
• Date/time formatting
• Path normalization
• Epoch handling

#Dependencies

• types/fpath (Level 1) - File path utilities

#Used By

• Main zip package - For file metadata
• All packages needing compression types or time handling

#Future Enhancements

• More compression methods (Bzip2, LZMA, etc.)
• Extended timestamps (ZIP64)
• Timezone support
• Path validation and security checks
• Unicode normalization for paths

#References

• ZIP File Format Specification
• MS-DOS Date and Time Format
• POSIX time standard (IEEE 1003.1)