tessl/maven-com-github-nscala-time--nscala-time_2-10

A Scala wrapper for Joda Time that provides more pleasant syntax like operators for addition, subtraction, and comparison of dates and times

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

nscala-time

Name: tessl/maven-com-github-nscala-time--nscala-time_2-10
Author: tessl

A Scala wrapper for Joda Time that provides idiomatic Scala syntax and operators for date and time operations. This library transforms Joda Time into a fluent, type-safe API with natural syntax like DateTime.now + 2.months and rich implicit conversions between temporal types.

Package Information

Package Name: com.github.nscala-time:nscala-time_2.10
Package Type: maven
Language: Scala
Installation: Add to build.sbt: libraryDependencies += "com.github.nscala-time" %% "nscala-time" % "1.8.0"

Core Imports

import com.github.nscala_time.time.Imports._

This single import provides access to all functionality including:

Type aliases for all Joda Time classes
Implicit enrichments for fluent operations
Static factory methods for convenient object creation
Duration and period builders

Basic Usage

import com.github.nscala_time.time.Imports._

// Create and manipulate dates
val now = DateTime.now
val tomorrow = now + 1.day
val nextWeek = now + 1.week

// Fluent date property manipulation
val specific = DateTime.now.withYear(2024).withMonth(12).withDay(25)

// Duration and period creation
val duration = 2.hours + 30.minutes + 15.seconds
val period = 3.months + 2.weeks + 5.days

// Interval operations
val interval = DateTime.now to DateTime.tomorrow
val isWithin = DateTime.now + 12.hours within interval

// String parsing with safety
val parsed = "2024-12-25T10:30:00".toDateTime
val safe = "invalid-date".toDateTimeOption // returns None

Architecture

nscala-time extends Joda Time with several key architectural patterns:

Type Enrichment: Every Joda Time class is enriched with Scala-friendly methods through implicit conversions
Builder Pattern: Duration and period builders provide fluent construction with automatic type conversions
Static Forwarders: Convenient access to Joda Time static methods through Scala objects
Operator Overloading: Mathematical and comparison operators for natural temporal arithmetic
Type Safety: Full compile-time type safety with implicit conversions between compatible types

Capabilities

Duration and Period Building

Fluent API for creating durations and periods with automatic unit conversions and arithmetic operations.

// Integer enrichments for time units
implicit class RichInt(n: Int) {
  def millis: DurationBuilder
  def seconds: DurationBuilder  
  def minutes: DurationBuilder
  def hours: DurationBuilder
  def days: Period
  def weeks: Period
  def months: Period
  def years: Period
}

class DurationBuilder(underlying: Period) {
  def +(that: DurationBuilder): DurationBuilder
  def -(that: DurationBuilder): DurationBuilder  
  def ago: DateTime
  def later: DateTime
  def from(dt: DateTime): DateTime
  def standardDuration: Duration
}

Duration and Period Builders

DateTime Operations

Rich operations on DateTime, LocalDate, LocalTime, and LocalDateTime with fluent property access and arithmetic.

implicit class RichDateTime(underlying: DateTime) {
  def +(duration: ReadableDuration): DateTime
  def -(duration: ReadableDuration): DateTime
  def +(period: ReadablePeriod): DateTime
  def -(period: ReadablePeriod): DateTime
  def +(builder: DurationBuilder): DateTime
  def -(builder: DurationBuilder): DateTime
  
  // Property access
  def year: DateTime.Property
  def month: DateTime.Property
  def day: DateTime.Property
  def hour: DateTime.Property
  def minute: DateTime.Property
  def second: DateTime.Property
  
  // Property setters
  def withYear(year: Int): DateTime
  def withMonth(month: Int): DateTime
  def withDay(day: Int): DateTime
  def withHour(hour: Int): DateTime
  def withMinute(minute: Int): DateTime
  def withSecond(second: Int): DateTime
}

DateTime Operations

Type Conversions

Seamless conversions between Joda Time types, Java standard library types, and Scala types with both safe and direct conversion methods.

implicit class RichString(s: String) {
  def toDateTime: DateTime
  def toLocalDate: LocalDate
  def toInterval: Interval
  def toDateTimeOption: Option[DateTime]
  def toLocalDateOption: Option[LocalDate] 
  def toIntervalOption: Option[Interval]
}

implicit class RichDate(underlying: java.util.Date) {
  def toLocalDateTime: LocalDateTime
  def toLocalDate: LocalDate
  def toLocalTime: LocalTime
}

implicit class RichSDuration(underlying: scala.concurrent.duration.Duration) {
  def toJodaDuration: Duration
}

implicit class RichDuration(underlying: Duration) {
  def toScalaDuration: scala.concurrent.duration.Duration
}

Type Conversions

Static Factory Methods

Convenient factory methods and utilities for creating temporal objects with enhanced Scala-friendly APIs.

object DateTime extends StaticDateTime {
  def now: DateTime
  def now(zone: DateTimeZone): DateTime
  def parse(str: String): DateTime
  def parse(str: String, formatter: DateTimeFormatter): DateTime
  def nextSecond: DateTime
  def nextMinute: DateTime
  def nextHour: DateTime
  def nextDay: DateTime
  def tomorrow: DateTime
  def nextWeek: DateTime
  def nextMonth: DateTime
  def nextYear: DateTime
  def yesterday: DateTime
  def lastSecond: DateTime
  def lastMinute: DateTime
  def lastHour: DateTime
  def lastDay: DateTime
  def lastWeek: DateTime
  def lastMonth: DateTime
  def lastYear: DateTime
}

Static Factory Methods

Type Definitions

Core type aliases that provide Scala-friendly names for Joda Time classes:

type DateTime = org.joda.time.DateTime
type LocalDate = org.joda.time.LocalDate
type LocalTime = org.joda.time.LocalTime
type LocalDateTime = org.joda.time.LocalDateTime
type Duration = org.joda.time.Duration
type Period = org.joda.time.Period
type Interval = org.joda.time.Interval
type DateTimeZone = org.joda.time.DateTimeZone
type DateTimeFormat = org.joda.time.format.DateTimeFormat
type Chronology = org.joda.time.Chronology
type YearMonth = org.joda.time.YearMonth
type MonthDay = org.joda.time.MonthDay
type Partial = org.joda.time.Partial

Ordering Support

Built-in ordering instances for all temporal types:

implicit val DateTimeOrdering: Ordering[DateTime]
implicit val LocalDateOrdering: Ordering[LocalDate] 
implicit val LocalTimeOrdering: Ordering[LocalTime]
implicit val LocalDateTimeOrdering: Ordering[LocalDateTime]
implicit val DurationOrdering: Ordering[Duration]