ordinales v1.0.1

ordinales

A small JavaScript package to retrieve the ordinal suffix/indicator of a number.

Note: This package only provides the ordinal suffixes (1ro, 2do, etc...), not the full words (primero, segundo, etc...)

Installation

npm install ordinales

Quick and simple usage

const ordinales = require("ordinales")

var ordinal = ordinales(5, "male")

console.log(ordinal)
    // => "5to"

As easy as that!

API

const ordinales = require("ordinales")
ordinales(input, options)

input

Type: Number or String
Possible values: Any integer / Any string.

If the input is a string, every number in the string is replaced with its suffixed form.

ordinales(1000, options)
    // => "1000mo"

ordinales("Ella es la 1 persona, y él la 2.", options)
    // => "Ella es la 1ra persona, y él la 2da."

ordinales("8", options)
    // => "8vo"

ordinales(-18, options)
    // => "-18vo"

ordinales({}, options) // Incorrect usage
    // => TypeError: Expected input to be Number or String, received object [object Object].

If the input is a number but not an integer, a TypeError will be thrown.

ordinales(Infinity, "male") // Incorrect usage
    // => TypeError: Expected integer, received Infinity.

ordinales(NaN, "female") // Incorrect usage
    // => TypeError: Expected integer, received NaN.

ordinales(8.7, "male") // Incorrect usage
    // => TypeError: Expected integer, received 8.7.

If the input is 0, Ordinales will return an empty suffix/indicator.

ordinales(0, "male")
ordinales("0", "female")
    // => "0"

ordinales(0, { "gender": "male", "onlySuffix": true })
    // => ""

options

Type: Object

The options argument can be an Object or a String. If a string is specified, it's used as the gender option. If an object is used, the following options can be specified:

ordinales(10, {

    "gender": gender,
    "beforeMaleNoun": beforeMaleNoun,
    "onlySuffix": onlySuffix

})
    // => "10mo" (modified depending on specified options.)

ordinales("3 ejemplo.", 8) // Incorrect usage
    // => TypeError: Expected options to be Object or String, received number 8.

ordinales(25) // Incorrect usage
    // => ReferenceError: Missing options parameter.    

options.gender

Type: String
Possible values: ["male", "female"]

This is the gender used in the suffix. It has no default value. So if it's not specified, a ReferenceError will be thrown. As shown before, you can pass a string as the options object to specify the gender instead.

ordinales(1, { "gender": "female" })
ordinales(1, "female")
    // => "1ra"

ordinales("Ella quedó en 5 lugar.", "male")
ordinales("Ella quedó en 5 lugar.", { "gender": "male" })
    // => "Ella quedó en 5to lugar."

ordinales(94, {}) // Incorrect usage
    // => ReferenceError: Missing gender in options object.

ordinales(39, { "gender": 100 }) // Incorrect usage
    // => TypeError: Expected gender to be String, received number 100.

ordinales(17, { "gender": "" }) // Incorrect usage
    // => TypeError: Expected gender to be "male" or "female", received ""

Ordinales doesn't support multiple genders when passing a string yet.

options.beforeMaleNoun

Type: Boolean
Possible values: [true, false]

In Spanish, the 1st (1ro) and 3rd (3ro) male suffixes are modified to 1er and 3er when placed before a male noun. For example:

:x: Este es mi 1ro auto.

:heavy_check_mark: Este es mi 1er auto.

If this option is true, the output will be modified to fit the mentioned rule. Ordinales can't automatically detect the gender of nouns yet.

ordinales("Este es mi 1 auto.", { "gender": "male" })
    // => "Este es mi 1ro auto." (incorrect)

ordinales("Este es mi 1 auto.", { "gender": "male", "beforeMaleNoun": true })
    // => "Este es mi 1er auto."

ordinales(3, { "gender": "female" })
ordinales(3, { "gender": "female", "beforeMaleNoun": true })
    // => "3ra"

As shown in the last example, if the ordinal suffix is female, using the beforeMaleNoun option won't modify the output.

ordinales(123, { "gender": "male", "beforeMaleNoun": "true" })
    // => TypeError: Expected beforeMaleNoun to be Boolean, received string "true".

options.onlySuffix

Type: Boolean
Possible values: [true, false]

If this option is true, only the suffix/indicator will be returned.

ordinales(127, { "gender": "female" })
    // => "127mo"

ordinales(127, { "gender": "female", "onlySuffix": true })
    // => "mo"

ordinales(53, { "gender": "male", "beforeMaleNoun": true })
    // => "53er"

ordinales(53, { "gender": "male", "beforeMaleNoun": true, "onlySuffix": true })
    // => "er"

This option won't modify the output if you specify a string.

ordinales("Ya es la 1000000 vez que pasa esto.", { "gender": "female" })
ordinales("Ya es la 1000000 vez que pasa esto.", { "gender": "female", "onlySuffix": true })
    // => "Ya es la 1000000ma vez que pasa esto."