This module provides miscellaneous facilities for working with strings, numbers, dates, and objects and arrays of these basic types.\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14482}{}\doxysubsection{deep\+Copy(obj)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14482}
Creates a deep copy of a primitive type, object, or array of primitive types.\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14483}{}\doxysubsection{deep\+Equal(obj1, obj2)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14483}
Returns whether two objects are equal.\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14484}{}\doxysubsection{is\+Empty(obj)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14484}
Returns true if the given object has no properties and false otherwise. This is O(1) (unlike {\ttfamily Object.\+keys(obj).length === 0}, which is O(\+N)).\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14485}{}\doxysubsection{has\+Key(obj, key)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14485}
Returns true if the given object has an enumerable, non-\/inherited property called {\ttfamily key}. \mbox{[}For information on enumerability and ownership of properties, see the MDN documentation.\mbox{]}(\href{https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties}{\texttt{ https\+://developer.\+mozilla.\+org/en-\/\+US/docs/\+Web/\+Java\+Script/\+Enumerability\+\_\+and\+\_\+ownership\+\_\+of\+\_\+properties}})\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14486}{}\doxysubsection{for\+Each\+Key(obj, callback)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14486}
Like Array.\+for\+Each, but iterates enumerable, owned properties of an object rather than elements of an array. Equivalent to\+: \begin{DoxyVerb}for (var key in obj) {
        if (Object.prototype.hasOwnProperty.call(obj, key)) {
                callback(key, obj[key]);
        }
}
\end{DoxyVerb}
\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14487}{}\doxysubsection{flatten\+Object(obj, depth)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14487}
Flattens an object up to a given level of nesting, returning an array of arrays of length \char`\"{}depth + 1\char`\"{}, where the first \char`\"{}depth\char`\"{} elements correspond to flattened columns and the last element contains the remaining object . For example\+: \begin{DoxyVerb}flattenObject({
    'I': {
        'A': {
            'i': {
                'datum1': [ 1, 2 ],
                'datum2': [ 3, 4 ]
            },
            'ii': {
                'datum1': [ 3, 4 ]
            }
        },
        'B': {
            'i': {
                'datum1': [ 5, 6 ]
            },
            'ii': {
                'datum1': [ 7, 8 ],
                'datum2': [ 3, 4 ],
            },
            'iii': {
            }
        }
    },
    'II': {
        'A': {
            'i': {
                'datum1': [ 1, 2 ],
                'datum2': [ 3, 4 ]
            }
        }
    }
}, 3)
\end{DoxyVerb}
 becomes\+: \begin{DoxyVerb}[
    [ 'I',  'A', 'i',   { 'datum1': [ 1, 2 ], 'datum2': [ 3, 4 ] } ],
    [ 'I',  'A', 'ii',  { 'datum1': [ 3, 4 ] } ],
    [ 'I',  'B', 'i',   { 'datum1': [ 5, 6 ] } ],
    [ 'I',  'B', 'ii',  { 'datum1': [ 7, 8 ], 'datum2': [ 3, 4 ] } ],
    [ 'I',  'B', 'iii', {} ],
    [ 'II', 'A', 'i',   { 'datum1': [ 1, 2 ], 'datum2': [ 3, 4 ] } ]
]
\end{DoxyVerb}
 This function is strict\+: \char`\"{}depth\char`\"{} must be a non-\/negative integer and \char`\"{}obj\char`\"{} must be a non-\/null object with at least \char`\"{}depth\char`\"{} levels of nesting under all keys.\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14488}{}\doxysubsection{flatten\+Iter(obj, depth, func)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14488}
This is similar to {\ttfamily flatten\+Object} except that instead of returning an array, this function invokes {\ttfamily func(entry)} for each {\ttfamily entry} in the array that {\ttfamily flatten\+Object} would return. {\ttfamily flatten\+Iter(obj, depth, func)} is logically equivalent to {\ttfamily flatten\+Object(obj, depth).for\+Each(func)}. Importantly, this version never constructs the full array. Its memory usage is O(depth) rather than O(n) (where {\ttfamily n} is the number of flattened elements).

There\textquotesingle{}s another difference between {\ttfamily flatten\+Object} and {\ttfamily flatten\+Iter} that\textquotesingle{}s related to the special case where {\ttfamily depth === 0}. In this case, {\ttfamily flatten\+Object} omits the array wrapping {\ttfamily obj} (which is regrettable).\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14489}{}\doxysubsection{pluck(obj, key)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14489}
Fetch nested property \char`\"{}key\char`\"{} from object \char`\"{}obj\char`\"{}, traversing objects as needed. For example, {\ttfamily pluck(obj, \char`\"{}foo.\+bar.\+baz\char`\"{})} is roughly equivalent to {\ttfamily obj.\+foo.\+bar.\+baz}, except that\+:


\begin{DoxyEnumerate}
\item If traversal fails, the resulting value is undefined, and no error is thrown. For example, {\ttfamily pluck(\{\}, \char`\"{}foo.\+bar\char`\"{})} is just undefined.
\item If \char`\"{}obj\char`\"{} has property \char`\"{}key\char`\"{} directly (without traversing), the corresponding property is returned. For example, `pluck(\{ \textquotesingle{}foo.\+bar'\+: 1 \}, \textquotesingle{}foo.\+bar\textquotesingle{}){\ttfamily is 1, not undefined. This is also true recursively, so}pluck(\{ \textquotesingle{}a\textquotesingle{}\+: \{ \textquotesingle{}foo.\+bar\textquotesingle{}\+: 1 \} \}, \textquotesingle{}a.\+foo.\+bar\textquotesingle{})\`{} is also 1, not undefined.
\end{DoxyEnumerate}\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14490}{}\doxysubsection{rand\+Elt(array)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14490}
Returns an element from \char`\"{}array\char`\"{} selected uniformly at random. If \char`\"{}array\char`\"{} is empty, throws an Error.\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14491}{}\doxysubsection{starts\+With(str, prefix)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14491}
Returns true if the given string starts with the given prefix and false otherwise.\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14492}{}\doxysubsection{ends\+With(str, suffix)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14492}
Returns true if the given string ends with the given suffix and false otherwise.\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14493}{}\doxysubsection{parse\+Integer(str, options)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14493}
Parses the contents of {\ttfamily str} (a string) as an integer. On success, the integer value is returned (as a number). On failure, an error is {\bfseries{returned}} describing why parsing failed.

By default, leading and trailing whitespace characters are not allowed, nor are trailing characters that are not part of the numeric representation. This behaviour can be toggled by using the options below. The empty string (`'\textquotesingle{}\`{}) is not considered valid input. If the return value cannot be precisely represented as a number (i.\+e., is smaller than {\ttfamily Number.\+MIN\+\_\+\+SAFE\+\_\+\+INTEGER} or larger than {\ttfamily Number.\+MAX\+\_\+\+SAFE\+\_\+\+INTEGER}), an error is returned. Additionally, the string `'-\/0\textquotesingle{}{\ttfamily will be parsed as the integer}0{\ttfamily , instead of as the IEEE floating point value}-\/0\`{}.

This function accepts both upper and lowercase characters for digits, similar to {\ttfamily parse\+Int()}, {\ttfamily Number()}, and \href{https://illumos.org/man/3C/strtol}{\texttt{ strtol(3\+C)}}.

The following may be specified in {\ttfamily options}\+:

\tabulinesep=1mm
\begin{longtabu}spread 0pt [c]{*{4}{|X[-1]}|}
\hline
\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Option   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Type   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Default   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Meaning    }\\\cline{1-4}
\endfirsthead
\hline
\endfoot
\hline
\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Option   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Type   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Default   }&\PBS\centering \cellcolor{\tableheadbgcolor}\textbf{ Meaning    }\\\cline{1-4}
\endhead
base   &number   &10   &numeric base (radix) to use, in the range 2 to 36    \\\cline{1-4}
allow\+Sign   &boolean   &true   &whether to interpret any leading {\ttfamily +} (positive) and {\ttfamily -\/} (negative) characters    \\\cline{1-4}
allow\+Imprecise   &boolean   &false   &whether to accept values that may have lost precision (past {\ttfamily MAX\+\_\+\+SAFE\+\_\+\+INTEGER} or below {\ttfamily MIN\+\_\+\+SAFE\+\_\+\+INTEGER})    \\\cline{1-4}
allow\+Prefix   &boolean   &false   &whether to interpret the prefixes {\ttfamily 0b} (base 2), {\ttfamily 0o} (base 8), {\ttfamily 0t} (base 10), or {\ttfamily 0x} (base 16)    \\\cline{1-4}
allow\+Trailing   &boolean   &false   &whether to ignore trailing characters    \\\cline{1-4}
trim\+Whitespace   &boolean   &false   &whether to trim any leading or trailing whitespace/line terminators    \\\cline{1-4}
leading\+Zero\+Is\+Octal   &boolean   &false   &whether a leading zero indicates octal   \\\cline{1-4}
\end{longtabu}


Note that if {\ttfamily base} is unspecified, and {\ttfamily allow\+Prefix} or {\ttfamily leading\+Zero\+Is\+Octal} are, then the leading characters can change the default base from 10. If {\ttfamily base} is explicitly specified and {\ttfamily allow\+Prefix} is true, then the prefix will only be accepted if it matches the specified base. {\ttfamily base} and {\ttfamily leading\+Zero\+Is\+Octal} cannot be used together.

{\bfseries{Context\+:}} It\textquotesingle{}s tricky to parse integers with Java\+Script\textquotesingle{}s built-\/in facilities for several reasons\+:


\begin{DoxyItemize}
\item {\ttfamily parse\+Int()} and {\ttfamily Number()} by default allow the base to be specified in the input string by a prefix (e.\+g., {\ttfamily 0x} for hex).
\item {\ttfamily parse\+Int()} allows trailing nonnumeric characters.
\item {\ttfamily Number(str)} returns 0 when {\ttfamily str} is the empty string (`'\textquotesingle{}\`{}).
\item Both functions return incorrect values when the input string represents a valid integer outside the range of integers that can be represented precisely. Specifically, `parse\+Int(\textquotesingle{}9007199254740993'){\ttfamily returns 9007199254740992.}
\item {\ttfamily Both functions always accept}-\/{\ttfamily and}+\`{} signs before the digit.
\item Some older Java\+Script engines always interpret a leading 0 as indicating octal, which can be surprising when parsing input from users who expect a leading zero to be insignificant.
\end{DoxyItemize}

While each of these may be desirable in some contexts, there are also times when none of them are wanted. {\ttfamily parse\+Integer()} grants greater control over what input\textquotesingle{}s permissible.\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14494}{}\doxysubsection{iso8601(date)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14494}
Converts a Date object to an ISO8601 date string of the form \char`\"{}\+YYYY-\/\+MM-\/\+DDTHH\+:\+MM\+:\+SS.\+sss\+Z\char`\"{}. This format is not customizable.\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14495}{}\doxysubsection{parse\+Date\+Time(str)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14495}
Parses a date expressed as a string, as either a number of milliseconds since the epoch or any string format that Date accepts, giving preference to the former where these two sets overlap (e.\+g., strings containing small numbers).\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14496}{}\doxysubsection{hrtime\+Diff(time\+A, time\+B)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14496}
Given two hrtime readings (as from Node\textquotesingle{}s {\ttfamily process.\+hrtime()}), where timeA is later than timeB, compute the difference and return that as an hrtime. It is illegal to invoke this for a pair of times where timeB is newer than timeA.\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14497}{}\doxysubsection{hrtime\+Add(time\+A, time\+B)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14497}
Add two hrtime intervals (as from Node\textquotesingle{}s {\ttfamily process.\+hrtime()}), returning a new hrtime interval array. This function does not modify either input argument.\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14498}{}\doxysubsection{hrtime\+Accum(time\+A, time\+B)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14498}
Add two hrtime intervals (as from Node\textquotesingle{}s {\ttfamily process.\+hrtime()}), storing the result in {\ttfamily timeA}. This function overwrites (and returns) the first argument passed in.\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14499}{}\doxysubsection{hrtime\+Nanosec(time\+A), hrtime\+Microsec(time\+A), hrtime\+Millisec(time\+A)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14499}
This suite of functions converts a hrtime interval (as from Node\textquotesingle{}s {\ttfamily process.\+hrtime()}) into a scalar number of nanoseconds, microseconds or milliseconds. Results are truncated, as with {\ttfamily Math.\+floor()}.\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14500}{}\doxysubsection{validate\+Json\+Object(schema, object)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14500}
Uses JSON validation (via JSV) to validate the given object against the given schema. On success, returns null. On failure, {\itshape returns} (does not throw) a useful Error object.\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14501}{}\doxysubsection{extra\+Properties(object, allowed)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14501}
Check an object for unexpected properties. Accepts the object to check, and an array of allowed property name strings. If extra properties are detected, an array of extra property names is returned. If no properties other than those in the allowed list are present on the object, the returned array will be of zero length.\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14502}{}\doxysubsection{merge\+Objects(provided, overrides, defaults)}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14502}
Merge properties from objects \char`\"{}provided\char`\"{}, \char`\"{}overrides\char`\"{}, and \char`\"{}defaults\char`\"{}. The intended use case is for functions that accept named arguments in an \char`\"{}args\char`\"{} object, but want to provide some default values and override other values. In that case, \char`\"{}provided\char`\"{} is what the caller specified, \char`\"{}overrides\char`\"{} are what the function wants to override, and \char`\"{}defaults\char`\"{} contains default values.

The function starts with the values in \char`\"{}defaults\char`\"{}, overrides them with the values in \char`\"{}provided\char`\"{}, and then overrides those with the values in \char`\"{}overrides\char`\"{}. For convenience, any of these objects may be falsey, in which case they will be ignored. The input objects are never modified, but properties in the returned object are not deep-\/copied.

For example\+: \begin{DoxyVerb}mergeObjects(undefined, { 'objectMode': true }, { 'highWaterMark': 0 })
\end{DoxyVerb}
 returns\+: \begin{DoxyVerb}{ 'objectMode': true, 'highWaterMark': 0 }
\end{DoxyVerb}
 For another example\+: \begin{DoxyVerb}mergeObjects(
    { 'highWaterMark': 16, 'objectMode': 7 }, /* from caller */
    { 'objectMode': true },                   /* overrides */
    { 'highWaterMark': 0 });                  /* default */
\end{DoxyVerb}
 returns\+: \begin{DoxyVerb}{ 'objectMode': true, 'highWaterMark': 16 }
\end{DoxyVerb}
\hypertarget{md_sfcode_node_modules_jsprim_README_autotoc_md14503}{}\doxysection{Contributing}\label{md_sfcode_node_modules_jsprim_README_autotoc_md14503}
See separate \mbox{\hyperlink{md_sfcode_node_modules_jsprim_CONTRIBUTING}{contribution guidelines}}. 