<commit_before>#Mezr

Mezr is a lightweight JavaScript utility library for measuring and comparing the dimensions and distances of HTML DOM elements in modern browsers (IE9+). Mezr has a bit more extended variations of jQuery's popular methods such as offset, offsetParent, width and height, and a few handy extras too such as place method which mimics jQuery UI's position method.

##Project goals

* Lightweight and performant (emphasis on performant).
* Support all modern browsers (IE9+).
* Well documented codebase (JSDoc syntax).
* Comprehensive unit tests (Qunit).

##API 0.3.0-alpha

* [.width()](#width)
* [.height()](#height)
* [.offset()](#offset)
* [.offsetParent()](#offsetparent)
* [.distance()](#distance)
* [.place()](#place)
* .overlap() (coming up in version 0.4)

&nbsp;

###`.width()`

Returns the width of an element in pixels. Accepts also the window object (for getting the viewport width) and the document object (for getting the width of the whole document) in place of element.

**Syntax**

`mezr.width( el [, includeScrollbar] [, includePadding ] [, includeBorder ] [, includeMargin ] )`

**Parameters**

* **`el`** - *element / window / document*
  * Accepts any DOM element, the document object or the window object.
* **`[includeScrollbar]`** - *boolean*
  * When set to true the element's vertical scrollbar width will be added to the return value (if visible). Root element is handled as an element that can not posess a scrollbar. The outermost scrollbar (viewport's scrollbar) is considered as a part of the window and the document.
* **`[includePadding]`** - *boolean*
  * When set to true the element's left and right padding will be added to the return value.
* **`[includeBorder]`** - *boolean*
  * When set to true the element's left and right border width will be added to the return value.
* **`[includeMargin]`** - *boolean*
  * When set to true the element's left and right margin will be added to the return value. Negative margin will be substracted from the return value.

**Returns** &raquo; *number*

The return value may be fractional when calculating the width of an element. In the case of window and document the value is always an integer.

&nbsp;

###`.height()`

Returns the height of an element in pixels. Accepts also the window object (for getting the viewport height) and the document object (for getting the height of the whole document) in place of element.

**Syntax**

`mezr.height( el [, includeScrollbar] [, includePadding ] [, includeBorder ] [, includeMargin ] )`

**Parameters**

* **`el`** - *element / window / document*
  * Accepts any DOM element, the document object or the window object.
* **`[includeScrollbar]`** - *boolean*
  * When set to true the element's horizontal scrollbar height will be added to the return value (if visible). Root element is handled as an element that can not posess a scrollbar. The outermost scrollbar (viewport's scrollbar) is considered as a part of the window and the document.
* **`[includePadding]`** - *boolean*
  * When set to true the element's top and bottom padding will be added to the return value.
* **`[includeBorder]`** - *boolean*
  * When set to true the element's top and bottom border width will be added to the return value.
* **`[includeMargin]`** - *boolean*
  * When set to true the element's top and bottom margin will be added to the return value. Negative margin will be substracted from the return value.

**Returns** &raquo; *number*

The return value may be fractional when calculating the height of an element. In the case of window and document the value is always an integer.

&nbsp;

###`.offset()`

Returns the element's offset, which in practice means the vertical and horizontal distance between the element's northwest corner and the document's northwest corner. By default the edge of the element's border is considered as the edge of the element, but you can make the function include the element's border width and padding in the return value as well.

**Syntax**

`mezr.offset( el [, includeBorder ] [, includePadding ] )`

**Parameters**

* **`el`** - *element / window / document*
  * Accepts any DOM element, the document object or the window object.
* **`[includeBorder]`** - *boolean*
  * When set to true the element's left and top border width will be added to the return value.
* **`[includePadding]`** - *boolean*
  * When set to true the element's left and top padding will be added to the return value.

**Returns** &raquo; *object*

* **`left`** - *number*
  * The element's left offset in pixels, value can be fractional.
* **`top`** - *number*
  * The element's top offset in pixels, value can be fractional.

&nbsp;

###`.offsetParent()`

Returns the element's offset parent. This function works in the same manner as the native elem.offsetParent method with a few tweaks and logic changes. The function accepts the window object and the document object in addition to DOM elements. Document object is considered as the base offset point against which the element/window offsets are compared to. This in turn means that the document object does not have an offset parent and returns null if provided as the element. Document is also considered as the window's offset parent. Window is considered as the offset parent of all fixed elements. Root and body elements are treated equally with all other DOM elements. For example body's offset parent is the root element if root element is positioned, but if the root element is static the body's offset parent is the document object.

**Syntax**

`mezr.offsetParent( el )`

**Parameters**

* **`el`** - *element / window / document*
  * Accepts any DOM element, the document object or the window object.

**Returns** &raquo; *element / null*

The return value is null if document object is provided as the element.

&nbsp;

###`.distance()`

Returns the vertical, horizontal and direct distance between two offset coordinates. Accepts direct offset as an object or alternatively an array in which case the the offset is retrieved automatically using mezr.offset method with the array's values as the function arguments. This function was originally intended to mimic jQuery's position method, but evolved into a lower level utility function to provide more control.

**Syntax**

`mezr.distance( coordFrom , coordTo )`

**Parameters**

* **`coordFrom`** - *object / array*
  * Object: must have left and top properties with numeric values (e.g. `{left: 10, top: -10}`).
  * Array: calls mezr.offset() using the array's values as the offset's arguments (e.g `[document.body, true, true]`).
* **`coordTo`** - *object / array*
  * Same specs as for coordFrom.  

**Returns** &raquo; *object*

* **`left`** - *number*
  * Horizontal distance between the two coordinates. Negative number if `coordFrom.left > coordTo.left`, otherwise positive.
  * `coordTo.left - coordFrom.left`
* **`top`** - *number*
  * Vertical distance between the two coordinates. Negative number if `coordFrom.top > coordTo.top`, otherwise positive.
  * `coordTo.top - coordFrom.top`
* **`direct`** - *number*
  * Direct distance between the two coordinates in pixels.
  * `Math.sqrt( Math.pow( returnObj.left, 2 ) + Math.pow( returnObj.top, 2 ) )`

&nbsp;

###`.place()`

Calculate an element's position (left/top CSS properties) when positioned relative to other elements, window or the document. This method is especially helpful in scenarios where the DOM tree is deeply nested and it's difficult to calculate an element's position using only CSS. The API is heavily inspired by the jQuery UI's position method.

There are a couple of things to note though.<commit_msg>Added code examples to readme.<commit_after>#Mezr

Mezr is a lightweight JavaScript utility library for measuring and comparing the dimensions and distances of HTML DOM elements in modern browsers (IE9+). Mezr has a bit more extended variations of jQuery's popular methods such as offset, offsetParent, width and height, and a few handy extras too such as place method which mimics jQuery UI's position method.

##Project goals

* Lightweight and performant (emphasis on performant).
* Support all modern browsers (IE9+).
* Well documented codebase (JSDoc syntax).
* Comprehensive unit tests (Qunit).

##API 0.3.0-alpha

* [.width()](#width)
* [.height()](#height)
* [.offset()](#offset)
* [.offsetParent()](#offsetparent)
* [.distance()](#distance)
* [.place()](#place)
* .overlap() (coming up in version 0.4)

&nbsp;

###`.width()`

Returns the width of an element in pixels. Accepts also the window object (for getting the viewport width) and the document object (for getting the width of the whole document) in place of element.

**Syntax**

`mezr.width( el [, includeScrollbar] [, includePadding ] [, includeBorder ] [, includeMargin ] )`

**Parameters**

* **`el`** - *element / window / document*
  * Accepts any DOM element, the document object or the window object.
* **`[includeScrollbar]`** - *boolean*
  * When set to true the element's vertical scrollbar width will be added to the return value (if visible). Root element is handled as an element that can not posess a scrollbar. The outermost scrollbar (viewport's scrollbar) is considered as a part of the window and the document.
* **`[includePadding]`** - *boolean*
  * When set to true the element's left and right padding will be added to the return value.
* **`[includeBorder]`** - *boolean*
  * When set to true the element's left and right border width will be added to the return value.
* **`[includeMargin]`** - *boolean*
  * When set to true the element's left and right margin will be added to the return value. Negative margin will be substracted from the return value.

**Returns** &raquo; *number*

The return value may be fractional when calculating the width of an element. In the case of window and document the value is always an integer.

**Examples**

```javascript
// Document width without viewport scrollbar.
// jQuery -> $(document).width()
var docWidth = mezr.width(document);

// Document width with viewport scrollbar.
// No jQuery alternative.
var docWidth = mezr.width(document, true);

// Window width without viewport scrollbar.
// jQuery -> $(window).width()
var winWidth = mezr.width(window);

// Window width with viewport scrollbar (handy for working with media queries).
// No jQuery alternative.
var winWidth = mezr.width(window, true);

// Element width with scrollbar.
// jQuery -> $('body').width()
var bodyWidth = mezr.width(document.body, true);

// Element width with scrollbar and padding.
// jQuery -> $('body').innerWidth()
var bodyWidth = mezr.width(document.body, true);

// Element width with scrollbar, padding and border.
// jQuery -> $('body').outerWidth()
var bodyWidth = mezr.width(document.body, true, true, true);

// Element width with scrollbar, padding, border and margin.
// jQuery -> $('body').outerWidth(true)
var bodyWidth = mezr.width(document.body, true, true, true, true);

// Element width without scrollbar.
// No jQuery alternative.
var bodyWidth = mezr.width(document.body);
```

&nbsp;

###`.height()`

Returns the height of an element in pixels. Accepts also the window object (for getting the viewport height) and the document object (for getting the height of the whole document) in place of element.

**Syntax**

`mezr.height( el [, includeScrollbar] [, includePadding ] [, includeBorder ] [, includeMargin ] )`

**Parameters**

* **`el`** - *element / window / document*
  * Accepts any DOM element, the document object or the window object.
* **`[includeScrollbar]`** - *boolean*
  * When set to true the element's horizontal scrollbar height will be added to the return value (if visible). Root element is handled as an element that can not posess a scrollbar. The outermost scrollbar (viewport's scrollbar) is considered as a part of the window and the document.
* **`[includePadding]`** - *boolean*
  * When set to true the element's top and bottom padding will be added to the return value.
* **`[includeBorder]`** - *boolean*
  * When set to true the element's top and bottom border width will be added to the return value.
* **`[includeMargin]`** - *boolean*
  * When set to true the element's top and bottom margin will be added to the return value. Negative margin will be substracted from the return value.

**Returns** &raquo; *number*

The return value may be fractional when calculating the height of an element. In the case of window and document the value is always an integer.

**Examples**

Check the examples for mezr.width(), same stuff applies to mezr.height().

&nbsp;

###`.offset()`

Returns the element's offset, which in practice means the vertical and horizontal distance between the element's northwest corner and the document's northwest corner. By default the edge of the element's border is considered as the edge of the element, but you can make the function include the element's border width and padding in the return value as well.

**Syntax**

`mezr.offset( el [, includeBorder ] [, includePadding ] )`

**Parameters**

* **`el`** - *element / window / document*
  * Accepts any DOM element, the document object or the window object.
* **`[includeBorder]`** - *boolean*
  * When set to true the element's left and top border width will be added to the return value.
* **`[includePadding]`** - *boolean*
  * When set to true the element's left and top padding will be added to the return value.

**Returns** &raquo; *object*

* **`left`** - *number*
  * The element's left offset in pixels, value can be fractional.
* **`top`** - *number*
  * The element's top offset in pixels, value can be fractional.

**Examples**

```javascript
// Get element offset.
var elemOffset = mezr.offset(document.getElementById('someElement'));
// => {left: ..., top: ...}
```

&nbsp;

###`.offsetParent()`

Returns the element's offset parent. This function works in the same manner as the native elem.offsetParent method with a few tweaks and logic changes. The function accepts the window object and the document object in addition to DOM elements. Document object is considered as the base offset point against which the element/window offsets are compared to. This in turn means that the document object does not have an offset parent and returns null if provided as the element. Document is also considered as the window's offset parent. Window is considered as the offset parent of all fixed elements. Root and body elements are treated equally with all other DOM elements. For example body's offset parent is the root element if root element is positioned, but if the root element is static the body's offset parent is the document object.

**Syntax**

`mezr.offsetParent( el )`

**Parameters**

* **`el`** - *element / window / document*
  * Accepts any DOM element, the document object or the window object.

**Returns** &raquo; *element / null*

The return value is null if document object is provided as the element.

**Examples**

```javascript
// Get fixed element's offset parent.
var offsetParent = mezr.offsetParent(document.getElementById('fixedElem'));
// => window
```

&nbsp;

###`.distance()`

Returns the vertical, horizontal and direct distance between two offset coordinates. Accepts direct offset as an object or alternatively an array in which case the the offset is retrieved automatically using mezr.offset method with the array's values as the function arguments. This function was originally intended to mimic jQuery's position method, but evolved into a lower level utility function to provide more control.

**Syntax**

`mezr.distance( coordFrom , coordTo )`

**Parameters**

* **`coordFrom`** - *object / array*
  * Object: must have left and top properties with numeric values (e.g. `{left: 10, top: -10}`).
  * Array: calls mezr.offset() using the array's values as the offset's arguments (e.g `[document.body, true, true]`).
* **`coordTo`** - *object / array*
  * Same specs as for coordFrom.  

**Returns** &raquo; *object*

* **`left`** - *number*
  * Horizontal distance between the two coordinates. Negative number if `coordFrom.left > coordTo.left`, otherwise positive.
  * `coordTo.left - coordFrom.left`
* **`top`** - *number*
  * Vertical distance between the two coordinates. Negative number if `coordFrom.top > coordTo.top`, otherwise positive.
  * `coordTo.top - coordFrom.top`
* **`direct`** - *number*
  * Direct distance between the two coordinates in pixels.
  * `Math.sqrt( Math.pow( returnObj.left, 2 ) + Math.pow( returnObj.top, 2 ) )`

**Examples**

```javascript
// Get distance by typing coordinates manually.
var dist = mezr.distance({left: 5, top: -5}, {left: -5, top: 5});
// => {left: -10, top: 10, direct: 14.142135623730951}

// Get distance using Mezr's offset function.
var dist = mezr.distance([elemFrom], [elemTo]);

// Mimic jQuery's .position() method.
var elem = document.getElementById('someElem');
var mezrPos = mezr.distance([mezr.offsetParent(elem), true], [elem]);
var jqPos = $(elem).position();
// jqPos.left === mezrPos.left
// jqPos.top === mezrPos.top
// However, note that jQuery .position() excludes the element's margins from the 
// left and top values which may or may not be wanted depending on the situation.
// Mezr always includes element's margins as part of the offset and you can not 
// exclude them via an option (at least yet). So, long story short, the mezrPos 
// values match jqPos values in the above case only if the element does not have 
// margins set.
```

&nbsp;

###`.place()`

Calculate an element's position (left/top CSS properties) when positioned relative to other elements, window or the document. This method is especially helpful in scenarios where the DOM tree is deeply nested and it's difficult to calculate an element's position using only CSS. The API is heavily inspired by the jQuery UI's position method.

There are a couple of things to note though.
{'fraction_non_alphanumeric': 0.10561646900872679, 'fraction_numerical': 0.002852987245468785, 'mean_word_length': 4.3237045860631325, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 16, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '154656', 'n_tokens_mistral': 4977, 'n_tokens_neox': 4726, 'n_words': 2385}