Values Types Checkers
Strings
isEmptyString
Returns true if and only if the parameter's value is an empty string, otherwise returns false.
Nothing notable, but this function may be demanded for the development of other Stylus functions and mixins. This function has been used even for the implementation of isDimensionlessQuantity, another value type checking function:
isDimensionlessQuantity(value)
return typeof(value) == "unit" && isEmptyString(unit(value))
isNonEmptyString
Returns true if and only if the parameter's value is a non-empty string, otherwise returns false.
isNonEmptyString(X) is not equivalent to !isEmptyString(X) because in the first case true will be returned only when the string is non-empty while in the second case also when the value is a non-string.The usage of !isNonEmptyString(X) is rather demanded. Although the double negation may confuse, this filtering out of everything except non-empty strings functionality may be useful.
isString
Returns true if the parameter's value is a string (either empty or no), otherwise returns false. The shorthand of typeof(value) == "string".
Quantities
Unlike the majority of programming languages, Stylus being the CSS preprocessor work with dimensional and dimensionless quantities, not only with plain numbers. For both of them typeof() check will return "unit" thus when the dimension presence or absence is critical, the additional check will required. For such target, among the following functions there are isDimensionalQuantity and isDimensionlessQuantity ones. Also, although the а isDimensionalOrDimensionlessQuantity is the equivalent of typeof(x) == "unit", it has the name from which it is clear that true will be returned for both dimensional and dimensionless quantities.
isDimensionalOrDimensionlessQuantity
Returns true if and only if the parameter's value is either dimensional or dimensionless quantity, otherwise returns false. Works same as typeof(value) == "unit" and, although has the long name, disambiguates about for dimensional or dimensionless quantity check performed (in this case for both).
log(isDimensionalOrDimensionlessQuantity(2px)) // true
log(isDimensionalOrDimensionlessQuantity(2)) // true
isDimensionalQuantity
Returns true if the parameter's value is a dimensional quantity, otherwise returns false, herewith it is required to specify via second parameter must the function consider the 0 as dimensional quantity or no. As known from CSS fundamentals, this styles definition language allows to omit the units if the quantity is 0 (by other words, 0 is equivalent to 0px, 0rem and combinations of 0 with any other units currently supported by CSS).
isDimensionalQuantity(2px, "MUST_CONSIDER_DIMENSIONLESS_ZERO_AS_DIMENSIONAL_QUANTITY") // true
isDimensionalQuantity(2, "MUST_CONSIDER_DIMENSIONLESS_ZERO_AS_DIMENSIONAL_QUANTITY") // false
isDimensionalQuantity(0, "MUST_CONSIDER_DIMENSIONLESS_ZERO_AS_DIMENSIONAL_QUANTITY") // true
isDimensionalQuantity(0, "MUST_NOT_CONSIDER_DIMENSIONLESS_ZERO_AS_DIMENSIONAL_QUANTITY") // false
In the above example the values of first parameter are hardcoded ones, but in practice commonly the value will dynamic (it means unknown at advance), that is why the second is always required.
isDimensionlessQuantity
Returns true if the parameter's value is a dimensionless quantity, otherwise returns false, herewith the 0 will always be considered as a dimensionless quantity.
isDimensionlessQuantity(2px) // false
isDimensionlessQuantity(2) // true
isDimensionlessQuantity(0) // true
isNaturalNumber
Returns true if and only if parameter's value is a dimensionless quantity representing the natural number.
p(isNaturalNumber(1)) // true
p(isNaturalNumber(0)) // false
p(isNaturalNumber(1.1)) // false
p(isNaturalNumber(1e+1)) // false
p(isNaturalNumber(-1)) // false
Booleans
Being the language without built-in type safety, Stylus has the automatic coercion of non-boolean values to booleans (for example in conditional expressions). However sometimes Stylus behaviour is different with JavaScript-like to which web programmers are accustomed. For example, the if someVariable check will be truthy (in Stylus language) even if someVariable has not been initialized.
definedVariable = true
if definedVariable
p("Obviously, it will be printed to console.")
if undefinedVariable
p("It will be printed too because 'typeof(undefinedVariable)' is 'ident' what will not be coerced to false.")
To avoid the unexpected bugs, the explicit checking like someVariable == true or someVariable == false checking is recommended, but isTrue(someVariable) and isFalse(someVariable) suggesting by this library are the alternatives.
isBoolean
The short alternative of a comparing expression typeof(x) == "boolean", where x is an arbitrary variable even it has not been initialized.
isFalse
The alternative of a comparing expression x == false, where x is and arbitrary variable even it has not been initialized.
isTrue
The alternative of a comparing expression x == true, where x is and arbitrary variable even it has not been initialized.
Nullables
The nullability has the shortcomings in Stylus. This functions group gives the higher safety level when working with potentially null values. For more specific information, see the theoretical reference below.
Theoretical Minimum: Nullability in Stylus
`null` Keyword
Consider the following code:
sample1 = null
p(sample1)
p(typeof(sample1))
p(sample1 == null)
p(typeof(sample1) == "null")
For now, the Stylus works as expected:
inspect: () inspect: 'null' inspect: false inspect: true
Non-existing Object Property
Consider the following code:
sample2 = {}
p(sample2.nonExistingProperty)
p(typeof(sample2.nonExistingProperty))
p(sample2.nonExistingProperty == null)
p(typeof(sample2.nonExistingProperty) == "null")
For now, the Stylus works as expected:
inspect: null inspect: 'null' inspect: true inspect: true
Function/Mixin with Rest Parameters Only
Consider the following code:
sampleFunction1(parameters...)
sample3 = parameters
p(sample3)
p(typeof(sample3))
p(sample3 == null)
p(typeof(sample3) == "null")
sampleFunction1()
The anomalies are starting here. Although sample3 == null is falsy, the typeof(sample3) == "null" is truthy:
inspect: () inspect: 'null' inspect: false inspect: true
Function/Mixin with Rest Parameters in Subsequent Position
Consider the following code:
sampleFunction2(parameter, restParameters...)
sample4 = restParameters
p("Checkpoint1")
p(sample4)
p("Checkpoint2")
p(typeof(sample4))
p(sample4 == null)
p(typeof(sample4) == "null")
sampleFunction2("TEST")
The output is:
inspect: "Checkpoint1" inspect: "Checkpoint2" inspect: 'null' inspect: false inspect: true
There are the following anomalies:
- The
p(sample4)has been ignored. - The
typeof(sample4) == "null"is truthy butsample4 == nullis falsy.
From above experiments we can conclude that the direct comparison with null is unsafe. Instead, the typeof(x) == "null or typeof(x) == "null comparisons should be used, but isNull/isNotNull functions suggested by YDF are the shorter alternatives.
isNotNull
Returns true for any values of parameter except null, thus returns false if and only if the value of parameter is null. It is not the equivalent ot x != null, because at it has been shown above the direct comparison with null not always works as expected.
isNull
Returns true if and only if the parameter's value is null, thus returns false for any other values of parameter. It is not the equivalent ot x != null, because at it has been shown above the direct comparison with null not always works as expected.
Others
isCalcExpression
Returns true if and only if the passed parameter is a Stylus literal (satisfies to typeof(value) == "literal"), herewith starts from calc(, otherwise returns false. Although there is no specific data type for calc expressions it is possible to analyze does the literal represents the calc expression or no, it is what this function does.
isFunction
Returns true if and only if parameter's value is a function, otherwise returns false. The shorthand of typeof(x) == "function".
isIdentifier
Returns true if and only if parameter's value is an identifier, otherwise returns false. The equivalent of typeof(x) == "ident".
isObject
Returns true if and only if parameter's value is an object, otherwise returns false. The shorthand of typeof(x) == "object".