/**
 * Provides a utility method used to deserialize a JSON symbol object returned by the REST API.
 *
 * @since 4.0
 * @see [Symbol](https://developers.arcgis.com/javascript/latest/api-reference/esri-symbols-Symbol.html)
 * @see [Using fromJSON() to create a class instance](https://developers.arcgis.com/javascript/latest/using-fromjson)
 */
import type { SymbolUnion } from "../types.js";

/**
 * Creates a new instance of an appropriate [Symbol](https://developers.arcgis.com/javascript/latest/api-reference/esri-symbols-Symbol.html) class and initializes it with values from a JSON object
 * generated from an ArcGIS product. The object passed into the input `json`
 * parameter often comes from a response to a query operation in the REST API or a
 * [toJSON()](https://pro.arcgis.com/en/pro-app/latest/tool-reference/conversion/features-to-json.htm)
 * method from another ArcGIS product. See the [Using fromJSON()](https://developers.arcgis.com/javascript/latest/using-fromjson)
 * topic in the Guide for details and examples of when and how to use this function.
 *
 * When you create a [MarkerSymbol](https://developers.arcgis.com/javascript/latest/api-reference/esri-symbols-MarkerSymbol.html), [SimpleMarkerSymbol](https://developers.arcgis.com/javascript/latest/api-reference/esri-symbols-SimpleMarkerSymbol.html) or
 * [PictureMarkerSymbol](https://developers.arcgis.com/javascript/latest/api-reference/esri-symbols-PictureMarkerSymbol.html) from a JSON object, you may specify a property angle to rotate the symbol.
 * Be aware that the angle in the JSON is different from [MarkerSymbol#angle](https://developers.arcgis.com/javascript/latest/api-reference/esri-symbols-MarkerSymbol.html#angle).
 * The angle in the JSON follows the traditional ArcGIS specification and is rotated counter-clockwise, whereas the angle in the
 * symbol is rotated clockwise.
 *
 * @param json - A JSON representation of the instance in the ArcGIS format. See
 *                      the [ArcGIS REST API documentation](https://developers.arcgis.com/documentation/common-data-types/symbol-objects.htm)
 *                      for examples of the structure of various input JSON objects.
 * @returns Returns a new instance of an appropriate Symbol class.
 * @example
 * // The angle=-30 in the JSON will create a symbol rotated -30 degrees counter-clockwise; that is,
 * // 30 degrees clockwise, which symbol.angle=30 would also produce.
 * let symbol = jsonUtils.fromJSON({
 *    "angle": -30,
 *    "xoffset": 0,
 *    "yoffset": 0,
 *    "type": "esriPMS",
 *    "url": "http://www.esri.com/careers/profiles/~/media/Images/Content/graphics/icons/socialmedia/pinterest1.png",
 *    "width": 18,
 *    "height": 18
 * });
 */
export function fromJSON(json: any): SymbolUnion;