Terminology & naming¶
This page defines the values, arguments, and naming conventions used in the guides.
Naming conventions¶
Methods use snake_case, such as time_zone_name() and relative_duration().
Option keys use camelCase, such as minimumFractionDigits.
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 | relative_duration() |
| Range | The interval between two values | — | two endpoints | date_range() |
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
relative_duration() 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 from_subtags(). |
| Modifiers | The optional settings layered onto a locale at construction: timeZone, calendar, currency. A settings object or dictionary. |
| Options bag | A per-call settings object (e.g. rounding/grouping options on number()). Keys use camelCase. |
| 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); time_zone_name() 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 (parse_number, parse_money, parse_date). |
| Negotiation | Choosing the best of your supported locales for a user, via CLDR language distance — see Negotiation & names. |
| Index buckets | Alphabetical section headers for a list (A–Z, 가나다, あかさ…). |
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 |
relative_duration() |
unit |
second · minute · hour · day · week · month · quarter · year (singular) |
relative_duration() |
numeric |
always · auto |
time_zone_name() |
style |
long (default) · short · shortOffset · longOffset · shortGeneric · longGeneric |
plural_category() |
returns | zero · one · two · few · many · other |
display_name() |
type |
language · region · script · calendar · currency |
supported_values() |
key |
timeZone · collation · numberingSystem · unit · transliterator |