or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-types.mddatetime-operations.mdduration-building.mdindex.mdlocal-datetime.mdordering.mdstring-parsing.md
tile.json

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

A Scala wrapper for Joda Time that provides idiomatic Scala syntax for date/time operations including operators for addition, subtraction, and comparison.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.github.nscala-time/nscala-time_2.10@2.34.x

To install, run

npx @tessl/cli install tessl/maven-com-github-nscala-time--nscala-time_2-10@2.34.0

index.mddocs/

nscala-time

nscala-time is a comprehensive Scala wrapper library around the Joda Time date and time API, offering idiomatic Scala syntax for date/time operations including operators for addition, subtraction, and comparison. It features enhanced functionality over Java's built-in Date and Calendar classes through immutable objects, thread-safe operations, and convenient method chaining.

Package Information

  • Package Name: nscala-time
  • Package Type: maven
  • Language: Scala
  • Organization: com.github.nscala-time
  • Installation: libraryDependencies += "com.github.nscala-time" %% "nscala-time" % "2.34.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 types
  • Enhanced static factory methods
  • Rich wrapper classes with operator overloading
  • Implicit conversions for seamless integration

Alternative selective imports:

import com.github.nscala_time.time.TypeImports._      // Type aliases only
import com.github.nscala_time.time.StaticForwarderImports._  // Static factories only
import com.github.nscala_time.time.Implicits._        // Implicit conversions only

Basic Usage

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

// Create dates with enhanced syntax
val now = DateTime.now()
val tomorrow = DateTime.tomorrow()
val nextWeek = now + 1.week

// Arithmetic operations
val future = now + 2.months + 3.days
val past = now - 1.year

// Fluent interface for time construction
val specificTime = now.withHour(14).withMinute(30).withSecond(0)

// String parsing with safe options
val parsed = "2023-12-25".toDateTimeOption
val withFormat = "25/12/2023".toDateTime("dd/MM/yyyy")

// Duration building
val duration = 2.hours + 45.minutes + 10.seconds
val durationInMillis = duration.millis

// Comparisons and intervals
val isAfter = now > yesterday()
val interval = now to tomorrow
val intervalDuration = interval.millis

Architecture

nscala-time is built around several key components:

  • Type Aliases: Direct access to Joda Time types with Scala naming conventions
  • Static Factories: Enhanced factory methods for creating date/time objects with relative time support
  • Rich Wrappers: Enhanced functionality for all Joda Time classes through implicit conversions
  • Duration Builder: Fluent builder pattern for creating complex durations and periods
  • Operator Overloading: Mathematical operators (+, -, comparisons) for intuitive date arithmetic
  • Implicit Conversions: Seamless integration with Scala types, Java Date, and Scala Duration

Capabilities

Core Date/Time Types

Core date and time type aliases and enhanced factory methods for creating and manipulating temporal objects.

type DateTime = org.joda.time.DateTime
type LocalDate = org.joda.time.LocalDate
type LocalDateTime = org.joda.time.LocalDateTime
type LocalTime = org.joda.time.LocalTime
type Duration = org.joda.time.Duration
type Period = org.joda.time.Period
type Interval = org.joda.time.Interval

// Enhanced factory objects
val DateTime: StaticDateTime
val LocalDate: StaticLocalDate  
val LocalDateTime: StaticLocalDateTime
val LocalTime: StaticLocalTime

Core Types and Factories

Duration and Period Building

Fluent builder system for creating durations and periods with natural language syntax and arithmetic operations.

class DurationBuilder(val underlying: Period) extends AnyVal {
  def +(that: DurationBuilder): DurationBuilder
  def -(that: DurationBuilder): DurationBuilder
  def ago(): DateTime
  def later(): DateTime
  def millis: Long
  def toDuration: Duration
  def toPeriod: Period
}

// Integer extensions for duration building
implicit class RichInt(val underlying: Int) extends AnyVal {
  def millis: DurationBuilder
  def seconds: DurationBuilder
  def minutes: DurationBuilder
  def hours: DurationBuilder
  def days: Period
  def weeks: Period
  def months: Period
  def years: Period
}

// Long extensions for duration conversion and arithmetic
implicit class RichLong(val underlying: Long) extends AnyVal {
  def toDateTime: DateTime
  def toDuration: Duration
  def -(duration: Duration): Duration
  def +(duration: Duration): Duration
  def *(duration: Duration): Duration
}

Duration and Period Building

Enhanced DateTime Operations

Comprehensive enhancements to DateTime with operator overloading, property accessors, and fluent setters.

implicit class RichDateTime(val underlying: DateTime) extends AnyVal {
  // Arithmetic operators
  def +(duration: ReadableDuration): DateTime
  def +(period: ReadablePeriod): DateTime
  def +(builder: DurationBuilder): DateTime
  def -(duration: ReadableDuration): DateTime
  def -(period: ReadablePeriod): DateTime
  
  // Property accessors
  def year: DateTime.Property
  def month: DateTime.Property
  def day: DateTime.Property
  def hour: DateTime.Property
  def minute: DateTime.Property
  def second: DateTime.Property
  
  // Fluent 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

String Parsing and Conversion

Safe string parsing capabilities with Option-based returns and custom format support for all major date/time types.

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

String Parsing

Local Date and Time Types

Enhanced functionality for local date and time types including arithmetic operations and property access.

implicit class RichLocalDate(ld: LocalDate) extends AnyVal
implicit class RichLocalDateTime(dt: LocalDateTime) extends AnyVal  
implicit class RichLocalTime(lt: LocalTime) extends AnyVal

// Enhanced static factories
object StaticLocalDate {
  def now(): LocalDate
  def parse(str: String): LocalDate
  // Additional factory methods
}

Local Date and Time

Ordering and Comparisons

Built-in ordering instances and comparison operators for all date/time types enabling seamless integration with Scala collections.

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]

Ordering and Comparisons

Types

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

// Java interop types
type Calendar = java.util.Calendar
type Date = java.util.Date

// Enhanced builder types
class DurationBuilder(val underlying: Period) extends AnyVal

// Property types
type DateTimeProperty = DateTime.Property
type LocalDateProperty = LocalDate.Property
type LocalDateTimeProperty = LocalDateTime.Property
type LocalTimeProperty = LocalTime.Property