@wider/utils_proto

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>Module: @wider/utils_proto/proto_object | YDR</title> <script src="scripts/prettify/prettify.js"> </script> <script src="scripts/prettify/lang-css.js"> </script>  <link type="text/css" rel="stylesheet" href="styles/bootstrap.min.css"> <link type="text/css" rel="stylesheet" href="styles/prettify-jsdoc.css"> <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css"> <link type="text/css" rel="stylesheet" href="styles/tui-doc.css"> </head> <body> <nav class="lnb" id="lnb"> <div class="logo" style="width: 50px"> <a href="http://y-d-r.co.uk" rel="noopener noreferrer" target="_blank"> <img src="http://y-d-r.co.uk/favicon.ico" width="100%" height="100%"> </a> </div> <div class="title"> <h1><a href="index.html" class="link">YDR</a></h1> <span class="version">v1.0.23</span> </div> <div class="search-container" id="search-container"> <input type="text" placeholder="Search"> <ul></ul> </div> <ol class="lnb-tab"> <li id="api-tab"> <a href="#"><h4>API</h4></a> </li> <li id="examples-tab"> <a href="#"><h4>Examples</h4></a> </li> </ol> <div class="lnb-examples hidden"><h3>Examples</h3><ul><li><a href="tutorial-Using Markdown with ydr_HTMLencode.html">Using Markdown with ydr_HTMLencode</a><button type="button" class="hidden toggle-subnav btn btn-link"> <span class="glyphicon glyphicon-plus"></span></button><div class="hidden" id="Using Markdown with ydr_HTMLencode_sub"></div></li><li><a href="tutorial-Using Object Prototype extensions.html">Using Object Prototype extensions</a><button type="button" class="hidden toggle-subnav btn btn-link"> <span class="glyphicon glyphicon-plus"></span></button><div class="hidden" id="Using Object Prototype extensions_sub"></div></li></ul></div><div class="lnb-api hidden"><h3>Modules</h3><ul><li><a href="module-@wider_utils_proto.html">@wider/utils_proto</a><button type="button" class="hidden toggle-subnav btn btn-link"> <span class="glyphicon glyphicon-plus"></span></button><div class="hidden" id="module:@wider/utils_proto_sub"><div class="member-type">Methods</div><ul class="inner"><li><a href="module-@wider_utils_proto.html#~init">init</a></li></ul></div></li><li><a href="module-@wider_utils_proto_proto_array.html">@wider/utils_proto/proto_array</a><button type="button" class="hidden toggle-subnav btn btn-link"> <span class="glyphicon glyphicon-plus"></span></button><div class="hidden" id="module:@wider/utils_proto/proto_array_sub"><div class="member-type">Methods</div><ul class="inner"><li><a href="module-@wider_utils_proto_proto_array.html#~keySort()">keySort()</a></li><li><a href="module-@wider_utils_proto_proto_array.html#~numericSortAsc()">numericSortAsc()</a></li><li><a href="module-@wider_utils_proto_proto_array.html#~permute()">permute()</a></li><li><a href="module-@wider_utils_proto_proto_array.html#~plainSortAsc()">plainSortAsc()</a></li><li><a href="module-@wider_utils_proto_proto_array.html#~plainSortDesc()">plainSortDesc()</a></li><li><a href="module-@wider_utils_proto_proto_array.html#~pushUnique()">pushUnique()</a></li></ul></div></li><li><a href="module-@wider_utils_proto_proto_array_test.html">@wider/utils_proto/proto_array/test</a><button type="button" class="hidden toggle-subnav btn btn-link"> <span class="glyphicon glyphicon-plus"></span></button><div class="hidden" id="module:@wider/utils_proto/proto_array/test_sub"></div></li><li><a href="module-@wider_utils_proto_proto_date.html">@wider/utils_proto/proto_date</a><button type="button" class="hidden toggle-subnav btn btn-link"> <span class="glyphicon glyphicon-plus"></span></button><div class="hidden" id="module:@wider/utils_proto/proto_date_sub"><div class="member-type">Methods</div><ul class="inner"><li><a href="module-@wider_utils_proto_proto_date.html#~toISOString">toISOString</a></li></ul></div></li><li><a href="module-@wider_utils_proto_proto_date_test.html">@wider/utils_proto/proto_date/test</a><button type="button" class="hidden toggle-subnav btn btn-link"> <span class="glyphicon glyphicon-plus"></span></button><div class="hidden" id="module:@wider/utils_proto/proto_date/test_sub"></div></li><li><a href="module-@wider_utils_proto_proto_function.html">@wider/utils_proto/proto_function</a><button type="button" class="hidden toggle-subnav btn btn-link"> <span class="glyphicon glyphicon-plus"></span></button><div class="hidden" id="module:@wider/utils_proto/proto_function_sub"><div class="member-type">Methods</div><ul class="inner"><li><a href="module-@wider_utils_proto_proto_function.html#~describe()">describe()</a></li></ul></div></li><li><a href="module-@wider_utils_proto_proto_function_test.html">@wider/utils_proto/proto_function/test</a><button type="button" class="hidden toggle-subnav btn btn-link"> <span class="glyphicon glyphicon-plus"></span></button><div class="hidden" id="module:@wider/utils_proto/proto_function/test_sub"></div></li><li><a href="module-@wider_utils_proto_proto_number.html">@wider/utils_proto/proto_number</a><button type="button" class="hidden toggle-subnav btn btn-link"> <span class="glyphicon glyphicon-plus"></span></button><div class="hidden" id="module:@wider/utils_proto/proto_number_sub"><div class="member-type">Methods</div><ul class="inner"><li><a href="module-@wider_utils_proto_proto_number.html#~bitsUpTo()">bitsUpTo()</a></li><li><a href="module-@wider_utils_proto_proto_number.html#~two()">two()</a></li></ul></div></li><li><a href="module-@wider_utils_proto_proto_number_test.html">@wider/utils_proto/proto_number/test</a><button type="button" class="hidden toggle-subnav btn btn-link"> <span class="glyphicon glyphicon-plus"></span></button><div class="hidden" id="module:@wider/utils_proto/proto_number/test_sub"></div></li><li><a href="module-@wider_utils_proto_proto_object.html">@wider/utils_proto/proto_object</a><button type="button" class="hidden toggle-subnav btn btn-link"> <span class="glyphicon glyphicon-plus"></span></button><div class="hidden" id="module:@wider/utils_proto/proto_object_sub"><div class="member-type">Methods</div><ul class="inner"><li><a href="module-@wider_utils_proto_proto_object.html#~assign()">assign()</a></li><li><a href="module-@wider_utils_proto_proto_object.html#~deepMerge()">deepMerge()</a></li></ul></div></li><li><a href="module-@wider_utils_proto_proto_object_test.html">@wider/utils_proto/proto_object/test</a><button type="button" class="hidden toggle-subnav btn btn-link"> <span class="glyphicon glyphicon-plus"></span></button><div class="hidden" id="module:@wider/utils_proto/proto_object/test_sub"></div></li><li><a href="module-@wider_utils_proto_proto_string.html">@wider/utils_proto/proto_string</a><button type="button" class="hidden toggle-subnav btn btn-link"> <span class="glyphicon glyphicon-plus"></span></button><div class="hidden" id="module:@wider/utils_proto/proto_string_sub"><div class="member-type">Methods</div><ul class="inner"><li><a href="module-@wider_utils_proto_proto_string.html#~asHTML()">asHTML()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~attrEncode()">attrEncode()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~camelIse()">camelIse()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~checkSum()">checkSum()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~checkSumValidate()">checkSumValidate()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~contextParse()">contextParse()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~deCamelIse()">deCamelIse()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~ellipses()">ellipses()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~escape()">escape()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~extendedCharCodeFixer()">extendedCharCodeFixer()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~formStrToXMLattr()">formStrToXMLattr()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~fuzzyValue()">fuzzyValue()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~HTMLencode()">HTMLencode()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~HTMLencodeInit">HTMLencodeInit</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~isHTML()">isHTML()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~isHTMLerror()">isHTMLerror()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~proper()">proper()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~regExpEncode()">regExpEncode()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~replaceSafe()">replaceSafe()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~searchEncode()">searchEncode()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~selectorEncode()">selectorEncode()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~simpleHTMLtoPlain()">simpleHTMLtoPlain()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~standardMarkups()">standardMarkups()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~stringEncode()">stringEncode()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~textSignature()">textSignature ()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~trim()">trim()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~unescape()">unescape()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~unHTMLencode()">unHTMLencode()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~wrapAsError()">wrapAsError()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~wrapAsOK()">wrapAsOK()</a></li><li><a href="module-@wider_utils_proto_proto_string.html#~XMLverify()">XMLverify()</a></li></ul></div></li><li><a href="module-@wider_utils_proto_proto_string_contextParse.html">@wider/utils_proto/proto_string/contextParse</a><button type="button" class="hidden toggle-subnav btn btn-link"> <span class="glyphicon glyphicon-plus"></span></button><div class="hidden" id="module:@wider/utils_proto/proto_string/contextParse_sub"><div class="member-type">Typedef</div><ul class="inner"><li><a href="module-@wider_utils_proto_proto_string_contextParse.html#~rowId">rowId</a></li><li><a href="module-@wider_utils_proto_proto_string_contextParse.html#~wider_context">wider_context</a></li></ul></div></li><li><a href="module-@wider_utils_proto_proto_string_test.html">@wider/utils_proto/proto_string/test</a><button type="button" class="hidden toggle-subnav btn btn-link"> <span class="glyphicon glyphicon-plus"></span></button><div class="hidden" id="module:@wider/utils_proto/proto_string/test_sub"></div></li></ul></div><div class="lnb-api hidden"><h3>Classes</h3><ul><li><a href="module-@wider_utils_proto_proto_string_contextParse-ContextParse.html">ContextParse</a><button type="button" class="hidden toggle-subnav btn btn-link"> <span class="glyphicon glyphicon-plus"></span></button><div class="hidden" id="module:@wider/utils_proto/proto_string/contextParse~ContextParse_sub"><div class="member-type">Methods</div><ul class="inner"><li><a href="module-@wider_utils_proto_proto_string_contextParse-ContextParse.html#toString">toString</a></li></ul></div></li></ul></div> </nav> <div id="resizer"></div> <div class="main" id="main"> <section> <header> <h2>@wider/utils_proto/proto_object</h2> </header> <article> <div class="container-overview"> <div class="description"><p>Additional methods for the javascript <strong>Function</strong> object</p></div> <dt> </dt> <dd> <dl class="details"> <dt class="tag-author">Author:</dt> <dd class="tag-author"> <ul> <li>Martin W Baker</li> </ul> </dd> <dt class="tag-copyright">Copyright:</dt> <dd class="tag-copyright"><ul class="dummy"><li>Copyright (C) 1985..2021 Martin Baker. http://y-d-r.co.uk</li></ul></dd> <dt class="tag-license">License:</dt> <dd class="tag-license"><ul class="dummy"><li>ISC Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.</li></ul></dd> </dl> </dd> </div> <h3 class="subsection-title">Methods</h3> <dl> <dt> <h4 class="name" id="~assign()"> <span class="type-signature"><span class="icon green">inner</span> </span>assign()<span class="signature">(…objects)</span><span class="type-signature"> → {Object}</span> <div class="container-source members"> <code><a href="proto_object_index.js.html">proto_object/index.js</a></code>, <code><a href="proto_object_index.js.html#line182">line 182</a></code> </div> </h4> </dt> <dd> <div class="description"> <p>perform an assign of all the <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/propertyIsEnumerable">enumerable</a> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty">own properties</a> of the given <strong>object</strong></p> <p>Unlike <code>Object.assign()</code> this will copy all the defined properties of the submitted items - so eg if your submitted object is writeOnly, it will still be copied leaving a write only result. You should not include the <code>this</code>object in the arguments list.</p> <p>Beware that when assigning functions, getters and setters, that they still remain those functions in their original objects but being called with <code>this</code> being the current object into which they are now also inserted.</p> <p>If a key in the current object is updated, then any defined properties you have already set are also overwritten.</p> </div> <div class="container-params"> <h5>Parameters:</h5> <table class="params"> <thead> <tr> <th>Name</th> <th>Type</th> <th>Attributes</th> <th class="last">Description</th> </tr> </thead> <tbody> <tr> <td class="name"><code>objects</code></td> <td class="type"> <span class="param-type">objects</span> </td> <td class="attributes"> <repeatable><br> </td> <td class="description last"><p>any number of objects whose members are to be assigned to this current object</p></td> </tr> </tbody> </table> </div> <h5>Throws:</h5> <dl> <dt> <div class="param-desc"> <p>if a key in this current object cannot be updated because the key is already in use and is not updatable</p> </div> </dt> <dd></dd> <dt> <dl> <dt> Type </dt> <dd> <span class="param-type">Error</span> </dd> </dl> </dt> <dd></dd> </dl> <div class="container-returns"> <h5>Returns:</h5> <span class="param-type">Object</span> - <p>being the same as this current object</p> </div> <dl class="details"> </dl> </dd> <dt> <h4 class="name" id="~deepMerge()"> <span class="type-signature"><span class="icon green">inner</span> </span>deepMerge()<span class="signature">(mergeItems, settings<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {Object}</span> <div class="container-source members"> <code><a href="proto_object_index.js.html">proto_object/index.js</a></code>, <code><a href="proto_object_index.js.html#line17">line 17</a></code> </div> </h4> </dt> <dd> <div class="description"> <p>Perform a deep merge of the current object with another object revising the current object</p> <p>A scan is made of all the <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/propertyIsEnumerable">enumerable</a> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty">own properties</a> of the given ** mergeItems ** and the action is chosen as below for each result found</p> <ul> <li> <p>if the result is <em><strong>undefined</strong></em> the value is deleted from the current object if it already exists</p> </li> <li> <p>if the result is another native {Object} it will also have a <code>wider_deepMerge()</code> method - this is called recursively to merge into the matching keyName of the current item (creating the keyName's empty object first if one does not yet exist)</p> </li> <li> <p>if the result is any other object the object itself is placed as this current value</p> </li> <li> <p>for any other value, eg string or function, the keyName is set to the value, retaining the defined properties of the new value (eg immutability, readonly, etc)</p> </li> </ul> <p>Important, child objects being deepMerged are never linked as the entire object - only enumerable members are processed. This means that the <strong>mergeItems</strong> object will never reflect changes in the current item and changes in the current item will not be reflected into the <strong>mergeItems</strong></p> <p>This does not perform the same impact as the package "npm install deepMerge" - the main differences are that object.wider_deepMerge():</p> <ul> <li> <p>is this faster or significantly faster</p> </li> <li> <p>updates your original object in situ so that any prior references to objects in it now refer to same object with possibly amended properties</p> </li> <li> <p>has control as to whether matching keyNames defer or overwrite</p> </li> <li> <p>has control over error handling</p> </li> <li> <p>has different management of merging arrays</p> </li> </ul> </div> <div class="container-params"> <h5>Parameters:</h5> <table class="params"> <thead> <tr> <th>Name</th> <th>Type</th> <th>Attributes</th> <th class="last">Description</th> </tr> </thead> <tbody> <tr> <td class="name"><code>mergeItems</code></td> <td class="type"> <span class="param-type">Object</span> </td> <td class="attributes"> </td> <td class="description last"><p>new items to merge into the current object.</p></td> </tr> <tr> <td class="name"><code>settings</code></td> <td class="type"> <span class="param-type">object</span> </td> <td class="attributes"> <optional><br> </td> <td class="description last"><p>settings that impact the behaviour - to use more than one value on the same key use a space separated list</p> <ul> <li><code>{ array : "push"}</code> if the new and the old values are arrays the new values are pushed into the array. As this always creates new elements in the array, this overrides the action of <strong>mode</strong> for arrays</li> <li><code>{ array : "pushUnique"}</code> as for <em><strong>push</strong></em> except that duplicate values are discarded</li> <li><code>{ array : "unshift"}</code> if the new and the old values are arrays the new values are unshifted into the array. This overrides the action of <strong>mode</strong> for arrays</li> <li><code>{ array : "unshiftUnique"}</code> as for <em><strong>push</strong></em> except that duplicate values are discarded</li> <li>`{ error : fn(Error) } if an error occurs it is sent to the function (eg <em><strong>console.error</strong></em>) and not, as per default, thrown. The value passes is the same error object that would have been thrown</li> <li>`{ mode : 'defer' } if a value appears in the <strong>mergeItems</strong> that is already in original object, the original object is not updated - the default is <strong>overwrite</strong>*</li> <li>'{ custom : {handler : fn(path,value), pattern : regExp]}` if the path to the item matches the regExp the callback is used to process the behaviour</li> </ul></td> </tr> </tbody> </table> </div> <h5>Throws:</h5> <dl> <dt> <div class="param-desc"> <p>when any of the following occur</p> <ul> <li>if the <strong>mergeItem</strong> is not a javascript native {Object}</li> <li>if the value of a <strong>mergeItem</strong> keyName is write only</li> <li>if the value in the current object of keyName is immutable or readOnly AND is different from the value being supplied</li> <li>if you use a combination of settings that when used are incompatible</li> </ul> <p>If an error is thrown and not trapped by your error setting function, your initial object will have been left partially updated</p> </div> </dt> <dd></dd> <dt> <dl> <dt> Type </dt> <dd> <span class="param-type">Error</span> </dd> </dl> </dt> <dd></dd> </dl> <div class="container-returns"> <h5>Returns:</h5> <span class="param-type">Object</span> - <p>the current object - use of this return value is optional</p> </div> <dl class="details"> </dl> </dd> </dl> </article> </section> </div> <footer> <img class="logo" src="http://y-d-r.co.uk/favicon.ico" style="width: 50px"> <div class="footer-text">Copyright Dr. Martin W. Baker 1985 onwards - MIT License</div> </footer> <script>prettyPrint();</script> <script src="scripts/jquery.min.js"></script> <script src="scripts/tui-doc.js"></script> <script src="scripts/linenumber.js"></script> <script> var id = 'module:@wider/utils_proto/proto_object_sub'.replace(/"/g, '_'); var selectedApi = document.getElementById(id); // do not use jquery selector var $selectedApi = $(selectedApi); $selectedApi.removeClass('hidden'); $selectedApi.parent().find('.glyphicon').removeClass('glyphicon-plus').addClass('glyphicon-minus'); showLnbApi(); </script> </body> </html>