Terminology & naming¶
This page defines the values, arguments, and naming conventions used in the guides.
Naming conventions¶
Methods use PascalCase, such as TimeZoneName() and RelativeDuration().
Options use typed objects with PascalCase properties, such as
new NumberOptions { MinimumFractionDigits = 2 }.
The temporal vocabulary¶
The date and time methods use these terms:
| Term | What it is | Has a direction? | Typical input | Method |
|---|---|---|---|---|
| Moment | A single point on the timeline (a date and a time together) | — | native date/time value | Moment() |
| Date | The calendar-date part of a moment (year-month-day) | — | a moment | Date() |
| Time | The clock-time part of a moment (hour-minute-second) | — | a moment | Time() |
| Duration | The magnitude of a span — "how long", no past/future | No (undirected) | seconds, or a unit breakdown | Duration() |
| Relative duration | A span oriented toward past or future — "3 days ago", "in 2 hours" | Yes (directed) | signed value + unit | RelativeDuration() |
| Range | The interval between two values | — | two endpoints | DateRange() |
Moment values
See Dates & times for accepted native values and timestamp units.
Duration vs relative duration
Duration(1222060) → "339:27:40" — a bare magnitude. relativeDuration(-3,
"day") → "3 days ago" — the same idea of elapsed time, but directed. If you
catch yourself wanting "ago" or "in" out of Duration(), you want
RelativeDuration() instead.
Core objects¶
| Term | Meaning |
|---|---|
| Locale | The identifier for a language + region + preferences — en_AU, fa-IR, or a full BCP-47 tag like fa-IR-u-nu-latn-ca-buddhist. Underscore and hyphen forms are both accepted. |
| Instance | A constructed Cosmo object, bound to one locale and its modifiers. You build it once and call methods on it. |
| Subtags | The pieces a locale decomposes into — language, script, region. You can construct from them directly with FromSubtags(). |
| Modifiers | The optional settings layered onto a locale at construction: timeZone, calendar, currency. A typed Modifiers object. |
| Options bag | A per-call settings object (e.g. rounding/grouping options on Number()). Uses typed objects with PascalCase properties. |
| Width | The verbosity of a formatted result, one scale shared by dates, units, and more: none · short · medium · long · full. |
Numbers & money¶
| Term | Meaning |
|---|---|
| Number | A locale-formatted decimal — grouping and decimal separators per locale. |
| Percentage | Formats a fraction as a percent (0.2 → "20%"). |
| Unit | A measured quantity with its unit (2.19 gigabytes, 26°C). |
| Money | A currency amount, formatted with the currency's symbol and placement. Cosmo only formats — it never converts between currencies. |
| Currency | The currency itself (its localised name or disambiguated symbol), independent of any amount. |
| Compact | Short magnitude notation — 1.2K, 1.2 thousand. |
| Scientific | Exponential notation — 1.2345E4. |
| Spellout | A number written in words — "one hundred twenty". |
| Ordinal | Ordinal text — "2nd". (For the ordinal plural category, see Messages & plurals.) |
| Symbol | A locale's notation symbol by name — e.g. the decimal mark "٫" in fa. |
Money is not currency conversion
Money(100, "AUD") formats 100 AUD in the locale's style. It does not
convert 100 of anything into AUD — convert the amount yourself first. See
Money & currency.
Locale, text & people¶
| Term | Meaning |
|---|---|
| Language / Country / Script / Calendar | The localised display name of a code — Language("en") in fa → "انگلیسی". |
| Direction | The locale's text direction — "ltr" or "rtl". |
| Time zone | An IANA zone (Australia/Sydney); TimeZoneName() gives its localised name. |
| Plural category | The CLDR plural class of a number (one, few, many, …) used to choose message forms. See Messages & plurals. |
| Collation | Locale-correct string ordering (sorting) — distinct from byte order. See Collation & text. |
| Transliterate / Romanize | Convert text between scripts; romanize is the to-Latin-then-ASCII special case (good for slugs). See Transliteration & parsing. |
| Confusable / Suspicious | Spoof detection (UTS #39): whether two strings look alike, or one string is spoof-prone. |
| Parse | The inverse of a formatter — turn locale-formatted text back into a value (ParseNumber, ParseMoney, ParseDate). |
Options & enumerations quick reference¶
These values recur across the library. Each row links to the relevant guide.
| Where it's used | Argument | Accepted values |
|---|---|---|
| Dates, units, lists, calendar names | width |
none · short · medium · long · full — see Width |
Number() / Percentage() / Money() |
number options | minimumIntegerDigits, min/maximumFractionDigits, min/maximumSignificantDigits, roundingMode, roundingIncrement, useGrouping |
| number options | roundingMode |
ceil · floor · expand · trunc · halfExpand (default) · halfTrunc · halfEven |
compare / sort / contains |
collation options | numeric (bool), caseFirst: upper · lower · false |
Contains() |
sensitivity |
base (default) · accent · case · variant |
Join() |
type |
conjunction (default) · disjunction · unit |
RelativeDuration() |
unit |
second · minute · hour · day · week · month · quarter · year (singular) |
RelativeDuration() |
numeric |
always · auto |
TimeZoneName() |
style |
long (default) · short · shortOffset · longOffset · shortGeneric · longGeneric |
PluralCategory() |
returns | zero · one · two · few · many · other |
DisplayName() |
type |
language · region · script · calendar · currency |
SupportedValues() |
key |
calendar · collation · currency · numberingSystem · timeZone · transliterator |