Softanza
StartFrançais
Softanza
StartFrançais
Research · narration

Date Programming Made Easy in Softanza

You're building a project timeline tracker. The client wants to see "in 2 weeks" instead of "14/10/2025". You need to add three months to a contract start date, but only if it falls on a weekday. Your code becomes a maze of calculations, string formatting, and edge cases.

by Mansour Ayouni · in the repository since 2025-09-30 · feature essay · no single Atlas area

The Problem We All Know

We've all been there. Date programming shouldn't be this hard.

A Different Approach

Softanza takes date handling back to how we actually think about time. Built on the Softanza Engine's rock-solid foundation, it lets you write code that mirrors natural language while running at native speed.

Let me show you what I mean.

Starting Simply

Haro
# Getting the day name in a string

? Today()
#--> 30/09/2025

# Or in a stzDate object form

oDate = TodayQ()	# Or oDate = new stzDate(:Today)
? oDate.Date()
#--> 30/09/2025

illustration

No ceremony. No configuration. Just ask for today's date and you get it. The Q suffix returns an object when you need to do more—a pattern you'll see throughout Softanza.

Creating a stzDate object

You can create an empty object and then decide what date to set in it:

Haro
o1 = new stzDate("")
? o1.Date()
#--> 10/10/2025

? o1.ToHuman() + NL
#--> today

#--

o1.SetDate(Tomorrow())
? o1.Date()
#--> 11/10/2025

? o1.ToHuman()
#--> tomorrow

illustration

Or you can initialise the date directly with the object creation:

Haro
# By providing a date in string in whatever format used for a date:

o1 = new stzDate("15/03/2024") # Or 2024-03-15 if you want
? o1.Date()
#--> 15/03/2024		# Format returned by default, can be changed as we will see later

# By providing the date component in numbers corresponding to Year, Month and then Day

o1 = new stzDate([ 2024, 3, 15 ])
? o1.Date() #--> 25/10/2025

# Or by providing a hahslist of named values in any order you want

o1 = new stzDate([ :Year = 2024, :Month = 3, :Day = 15 ])
? o1.Date() #--> 25/10/2025

# Or even using a natural expression like this

? Today() #--> 10/10/2025
o1 = new stzDate("In 15 days")
? o1.Date() #--> 25/10/2025

illustration

Smart Navigation Methods

Create a stzDate object and start navigating time immediately with this ritch set of natural-oriented methods:

Haro
o1 = new stzDate("10/10/2025")

? o1.NextDay()
#--> 11/10/2025

? o1.PreviousDay()
#--> 09/10/2025

? o1.NextWeekday()
#--> 13/10/2025

? o1.PreviousWeekday()
#--> 09/10/2025

? o1.NextMonday()
#--> 13/10/2025

? o1.FirstDayOfMonth()
#--> 01/10/2025

? o1.LastDayOfMonth()
#--> 31/10/2025

? o1.StartOfMonth()
#--> 01/10/2025

? o1.EndOfMonth()
#--> 31/10/2025

? o1.StartOfYear()
#--> 01/01/2025

? o1.EndOfYear()
#--> 31/12/2025

? o1.DayAfterMonthEnd()
#--> 31/10/2025

? o1.DayBeforeMonthStart()
#--> 01/10/2025

? o1.DayAfterYearEnd()
#--> 31/12/2025

? o1.DayBeforeYearStart()
#--> 01/01/2025

? o1.NextEndOfMonth()
#--> 31/10/2025

? o1.PreviousEndOfMonth()
#--> 31/10/2025

? o1.NextStartOfMonth()
#--> 01/10/2025

? o1.PreviousStartOfMonth()
#--> 01/10/2025

? o1.MidMonth()
#--> 16/10/2025

? o1.FirstWeekdayOfMonth()
#--> 01/10/2025

? o1.LastWeekdayOfMonth()
#--> 31/10/2025

illustration

Arithmetic That Makes Sense

Remember that project deadline calculation?

Haro
oDate = new stzDate("01/01/2025")
? oDate + "2 months"
#--> 01/03/2025

illustration

No imports. No helper functions. No manual day calculations. Just add "2 months" like you'd say it out loud.

This works because Softanza understands:

Haro
oDate = new stzDate("15/06/2024")

# All of these just work
? oDate + 30                    # days
#--> 15/07/2024

? oDate + 15                    # Add 15 days
#--> 30/06/2024

# Chain operations naturally
oDate { AddMonths(3) AddYears(1) ? ToString() }
#--> 15/09/2025

illustration

Comparisons Without Ceremony

Haro
oDate1 = StzDateQ("15/06/2024")
oDate2 = StzDateQ("20/06/2024")

? oDate1 < oDate2               #--> TRUE
? oDate1 < "20/06/2024"         #--> TRUE (compares with strings too)

# Calculate the difference
? oDate2 - oDate1               #--> 5

illustration

The code reads like the logic in your head.

Calculating Days, Months, and Years Between Dates

Durations can be computed and returned in whichever unit you need using these methods:

Haro
oDate1 = StzDateQ("01/01/2025")
oDate2 = StzDateQ("31/12/2027")

? oDate1.DaysToN(oDate2)
#--> 1094

# Or more simply:
? oDate2 - oDate1
#--> 1094

? oDate1.MonthsToN(oDate2)
#--> 35

? oDate1.YearsToN(oDate2)
#--> 2

illustration

NOTE: Softanza also provides a class called stzDuration, specialized in this area, which will be documented in its own article.

The Human Touch

That client requirement about showing "in 2 weeks" instead of dates?

Haro
o1 = new stzDate(:Today)
? o1.ToHuman()                  #--> today

o1 + "1 day"
? o1.ToHuman()                  #--> tomorrow

o1 - "2 days"
? o1.ToHuman()                  #--> yesterday

o1 + "2 weeks"
? o1.ToRelative()               #--> in 1 week

illustration

Just human-readable output that adapts to the time span.

Real-World Scenario: Age Calculation

Standard code:

Haro
# Calculate age - manual date math required
cBirthday = "15/06/1990"
cToday = date()

# Parse dates, extract years, handle edge cases...
# What if birthday hasn't occurred this year yet?
# Complex logic needed!

illustration

Softanza approach:

Haro
oBirthday = new stzDate("15/06/1990")
? oBirthday.Age()
#--> 35

illustration

One line. Handles all edge cases automatically.

Localization Made Simple

Standard code:

Haro
# Get day name

cDay = TimeList()[2]  # Remember: index 2 is full weekday name
? cDay
#--> Saturday

# French? You'll need to write your own translation logic...

illustration

Softanza:

Haro
oDate = new stzDate("27/09/2025")

? oDate.Day()
#--> Saturday

? oDate.DayIn(:French)
#--> Samedi

? oDate.DayIn(:Arabic)
#--> السبت

illustration

Built-in multilingual support. No translation tables needed.

Smart Inspection

Haro
oDate = StzDateQ("15/07/2024")
oDate {
    ? Year()                    #--> 2024
    ? MonthNumber()             #--> 7
    ? DayNumber()               #--> 15
    ? DayOfWeek()               #--> 1
    ? DayOfYear()               #--> 197
}

illustration

Every aspect of a date is accessible with clarity without the need of remembering standard Haro TimeList() indices.

Julian Day Conversion

Working with astronomical data, historical dates, or needing a universal date representation? Julian day numbers have you covered.

Convert current date to Julian day number:

Haro
o1 = new stzDate("") # Or any date you would supply instead of ""
? o1.ToJulianDay()
#--> 2460958

illustration

Create a date from a Julian day number:

Haro
o1 = new stzDate("")
o1.FromJulianDay(2460570)
? o1.Content()
#--> 16/09/2024	(the corresponding Gregorian date)

illustration

Julian day conversion runs at native speed while providing a direct bridge to scientific computing and historical timelines.

Validation Built-In

Haro
? IsDate("20/10/2025")          #--> TRUE
? IsDate("20/10/20025")         #--> FALSE

try
    oDate = StzDateQ("32/13/2024")  # Invalid
catch
    ? "Invalid date detected"
done

illustration

Errors are caught early with clear messages.

Performance Matters

All this expressiveness runs on the Softanza Engine's native date engine. Operations complete in microseconds. You're not trading performance for convenience. You're getting both.

Comparative Analysis

Task Python/Java/JS Softanza
Get today Various imports/objects Today() or TodayQ()
Add months Special methods/libraries oDate + "2 months"
Compare .compareTo(), .isBefore() oDate1 < oDate2
Difference Manual calculation oDate2 - oDate1
Human format External libraries oDate.ToHuman()
Localize Complex formatters oDate.DayIn(:French)
Calculate age Manual date math oBirthDate.Age()
Validate Try/catch parsing IsDate(cString)
Julian day Manual conversion oDate.ToJulianDay()

Final Thoughts

Softanza's date programming feels like a breath of fresh air. It prioritizes developer experience without compromising performance, making it ideal for projects where dates are central (e.g., scheduling apps, timelines, or user interfaces). The human-readable output, localization features, and Julian day conversion are particularly compelling for both client-facing applications and scientific computing tasks.

Related reading

Cite

Mansour Ayouni. "Date Programming Made Easy in Softanza". Softanza narrations, 2025. https://mayouni.github.io/stzsite/en/narrations/stzdate-date-programming-in-softanza.html

Not run: its code touches files, the network, the clock or chance. The article is published as written; its blocks are illustrations. The code of the articles is Haro code. Where an article was written before the language took its present name, the name was changed and nothing else. Genre, area and series read from the file's name, the year from its first commit: derived, until the article carries its own header. The file on GitHub(opens in a new tab)