/\*\*

- @ngdoc directive
- @name select
- @restrict E
-
- @description
- HTML `select` element with AngularTS data-binding.
-
- The `select` directive is used together with {@link ngModel `ngModel`} to provide data-binding
- between the scope and the `<select>` control (including setting default values).
- It also handles dynamic `<option>` elements, which can be added using the {@link ngRepeat `ngRepeat}` or
- {@link ngOptions `ngOptions`} directives.
-
- When an item in the `<select>` menu is selected, the value of the selected option will be bound
- to the model identified by the `ngModel` directive. With static or repeated options, this is
- the content of the `value` attribute or the textContent of the `<option>`, if the value attribute is missing.
- Value and textContent can be interpolated.
-
- The {@link select.SelectController select controller} exposes utility functions that can be used
- to manipulate the select's behavior.
-
- ## Matching model and option values
-
- In general, the match between the model and an option is evaluated by strictly comparing the model
- value against the value of the available options.
-
- If you are setting the option value with the option's `value` attribute, or textContent, the
- value will always be a `string` which means that the model value must also be a string.
- Otherwise the `select` directive cannot match them correctly.
-
- To bind the model to a non-string value, you can use one of the following strategies:
- - the {@link ng.ngOptions `ngOptions`} directive
- ({@link ng.select#using-select-with-ngoptions-and-setting-a-default-value})
- - the {@link ng.ngValue `ngValue`} directive, which allows arbitrary expressions to be
- option values ({@link ng.select#using-ngvalue-to-bind-the-model-to-an-array-of-objects Example})
- - model $parsers / $formatters to convert the string value
- ({@link ng.select#binding-select-to-a-non-string-value-via-ngmodel-parsing-formatting Example})
-
- If the viewValue of `ngModel` does not match any of the options, then the control
- will automatically add an "unknown" option, which it then removes when the mismatch is resolved.
-
- Optionally, a single hard-coded `<option>` element, with the value set to an empty string, can
- be nested into the `<select>` element. This element will then represent the `null` or "not selected"
- option. See example below for demonstration.
-
- ## Choosing between `ngRepeat` and `ngOptions`
-
- In many cases, `ngRepeat` can be used on `<option>` elements instead of {@link ng.directive:ngOptions
- ngOptions} to achieve a similar result. However, `ngOptions` provides some beneits:
- - more flexibility in how the `<select>`'s model is assigned via the `select` **`as`** part of the
- comprehension expression
- - reduced memory consumption by not creating a new scope for each repeated instance
- - increased render speed by creating the options in a documentFragment instead of individually
-
- Specifically, select with repeated options slows down significantly starting at 2000 options in
- Chrome and Internet Explorer / Edge.
-
-
- @param {string} ngModel Assignable AngularTS expression to data-bind to.
- @param {string=} name Property name of the form under which the control is published.
- @param {string=} multiple Allows multiple options to be selected. The selected values will be
-     bound to the model as an array.
- @param {string=} required Sets `required` validation error key if the value is not entered.
- @param {string=} ngRequired Adds required attribute and required validation constraint to
- the element when the ngRequired expression evaluates to true. Use ngRequired instead of required
- when you want to data-bind to the required attribute.
- @param {string=} ngChange AngularTS expression to be executed when selected option(s) changes due to user
- interaction with the select element.
- @param {string=} ngOptions sets the options that the select is populated with and defines what is
- set on the model on selection. See {@link ngOptions `ngOptions`}.
- @param {string=} ngAttrSize sets the size of the select element dynamically. Uses the
- {@link guide/interpolation#-ngattr-for-binding-to-arbitrary-attributes ngAttr} directive.
- \*/
