\r\n \r\n# [UseBase:
Encode and Decode Numbers](https://github.com/NaN-NaN-sempai/useBase)\r\n\r\n
\r\n ![\"UseBase](\"https://raw.githubusercontent.com/NaN-NaN-sempai/useBase/main/logo.png\" "\\"UseBase")
\r\n\r\n\r\n
\r\n
\r\n\r\n[](https://www.npmjs.com/package/usebase)\r\n\r\n
\r\n[](https://github.com/NaN-NaN-sempai/useBase)\r\n[](https://wa.me/5574981395580?text=I%20came%20from%20npm!)\r\n\r\n
\r\n\r\n[](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)\r\n\r\n\r\n
\r\n\r\n## About\r\n[UseBase](https://github.com/NaN-NaN-sempai/useBase) is a versatile JavaScript library designed to simplify the process of encoding and decoding numbers using various numeral bases. Whether you need to represent integers in binary, hexadecimal, custom character sets, or even emojis.\r\n\r\nAbout it's usage, `useBase` is a function that recieve a param `base` (optional), a string or array containing the base to be used, the default value is: `abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ`.\r\n\r\n`useBase` returns a object with two functions `encode` and `decode`, and a read-only value `base`, containing the `base` used to create this instance.\r\n\r\n - `encode` recieve two params, `integer` the number to be encoded and `auxArray` (optional) the array that the function uses as auxiliary array to store the values when the `base` is a array (don't pass any value if you dont know what you are doing). It returns a string or array of the `integer` encoded, the returned value have two proto properties:\r\n - `raw` property containing the `integer` param used to encode this value.\r\n - `base` property containing the `base` used to create this `useBase` instance.\r\n\r\n - `decode` recieve one param, `value` a encoded string or array. It returns a decode number, the returned value have a proto value:\r\n - `base` property containing the `base` used to create this `useBase` instance.\r\n\r\n\r\n## Installing\r\nInstall the package using npm:\r\n```css\r\nnpm install usebase\r\n```\r\n\r\nOnce the package is installed, you can import useBase to your project:\r\n\r\n```javascript\r\nimport useBase from \"usebase\";\r\n\r\nuseBase().encode(42); // returns \"Q\"\r\n```\r\n\r\nIf you are using `CommomJS`, there are some ways to import the module, one of them is using the import async function:\r\n\r\n```javascript\r\nimport(\"usebase\").then(({ default: useBase }) => {\r\n useBase().encode(42); // returns \"Q\"\r\n});\r\n\r\n// or in your async function\r\nconst { default: useBase } = await import(\"usebase\");\r\n\r\nuseBase().encode(42); // returns \"Q\"\r\n```\r\n\r\n### CDN\r\nUsing jsDelivr CDN (browser module):\r\n```html\r\n\r\n\r\n\r\n```\r\n\r\nUsing unpkg CDN:\r\n```html\r\n\r\n\r\n\r\n```\r\n\r\n## Example\r\nThere is a simple example of usage:\r\n\r\n```javascript\r\nuseBase().encode(42); // returns \"Q\"\r\n\r\nuseBase().decode(\"Q\"); // returns 42\r\n```\r\n\r\n### Using the Proto Properties\r\nThe `useBase` function have some proto properties containing some built-in bases: \r\n\r\n```javascript\r\nuseBase.base2; /* or */ useBase.binary;\r\n\r\nuseBase.base5; /* or */ useBase.quinary;\r\n\r\nuseBase.base8; /* or */ useBase.octal;\r\n\r\nuseBase.base12; /* or */ useBase.duodecimal;\r\n\r\nuseBase.base16; /* or */ useBase.hexadecimal;\r\n\r\nuseBase.base32;\r\n\r\nuseBase.base34;\r\n\r\nuseBase.base62;\r\n\r\nuseBase.base64;\r\n\r\n// usage example:\r\nuseBase.binary.encode(42); // returns \"101010\"\r\n\r\nuseBase.octal.decode(\"52\"); // returns 42\r\n```\r\n\r\nUsing the `raw` proto property from the `enconde` returned value, you can easily translate the value from a base to another:\r\n\r\n```javascript\r\nlet valueInBinary = useBase.binary.encode(42); // \"101010\"\r\n\r\nlet valueInOctal = useBase.octal.encode(valueInBinary.raw); // \"52\"\r\n```\r\n\r\n### Custom Bases\r\nUsing custom bases:\r\n\r\n```javascript\r\n// using a custom base2 (binary)\r\nuseBase(\"01\").encode(42); // returns \"101010\" \r\n\r\n// using a custom base8 (octal)\r\nuseBase(\"01234567\").decode(\"52\"); // returns 42\r\n\r\n// using a custom base\r\nuseBase(\"MYBASE\").encode(42); // returns \"YYM\"\r\n```\r\n\r\n### Multiple Instances\r\nYou can also save multiple instances and use them as you want:\r\n\r\n```javascript\r\nimport useBase from \"usebase\";\r\nconst { base2, base8, base12, base16, base32, base34, base62, base64 } = useBase;\r\n\r\n// or with custom bases\r\n\r\nconst base2 = useBase(\"01\"); // binary\r\n\r\nconst base8 = useBase(\"01234567\"); // octal\r\n\r\nconst base10 = useBase(\"0123456789\"); // decimal\r\n\r\nconst base16 = useBase(\"0123456789ABCDEF\"); // hexadecimal\r\n\r\nconst baseLetters = useBase(\"abcdefghijklmnopqrstuvwxyz\"); // alphabet\r\n\r\nconst baseLettersAndUpperCase = useBase(); // alphabet and UpperCase alphabet\r\n```\r\n\r\n### Base as Array\r\nUsing arrays:\r\n\r\n```javascript\r\nlet myArray = \"The answer to life, the universe and everything is 42\".split(\" \");\r\nconst base42 = useBase(myArray); // base of hitchhiker's guide to the galaxy\r\n\r\nlet myEncode = base42.encode(42); // returns array (2) ['the', 'to']\r\n\r\nlet myDecode = base42.decode(myEncode); // returns 42\r\n```\r\n\r\n### Special Characters\r\nSome special character use more than one space per character inside a string so you can't use it as string nor split to use as an array.\r\nWe need to split it using another method and pass this new array to useBase\r\n\r\n```javascript\r\n// function to split special characters\r\nconst splitPlus = (string) => [...new Intl.Segmenter().segment(string)].map(x => x.segment);\r\n\r\nlet myArray = splitPlus(\"«»©®℗™×='‘’‚‛¬–÷—“”„‟⁄\");\r\nconst baseSpecialChars = useBase(myArray); // Special characteres\r\n\r\nbaseSpecialChars.encode(42); // returns (2) ['»', '‟']\r\n\r\nlet myOtherArray = splitPlus(\"😀😁😂🤣😃😄😅😆😉😊😋😎😍😘🥰😗\");\r\nconst base16AsEmoji = useBase(myOtherArray); // Hexademojinal 🤣\r\n\r\nbase16AsEmoji.encode(42); // returns array (2) ['😂', '😋']\r\n```\r\n\r\n## Errors\r\nList of error throws:\r\n-  - If useBase `base` param is given but its not a string or array: \"Param 'base' must be of type String or Array\".\r\n-  - If encode `integer` param is not given as a number: \"Param 'number' must be of type Int\".\r\n-  - If encode `auxArray` param is given but it is not an array: \"Param 'auxArray' must be an array\".\r\n-  - If decode `value` param is not given as a string or array: \"Param 'value' must be of type String or Array\".\r\n\r\n\r\nList of possible errors and cautions you need to take:\r\n-  - If useBase `base` param includes the same value 2 or more times: The result of encoding and decoding may be incorrect.\r\n-  - If encode `integer` param is given as a negative number: It will return `undefined` as useBase does not support negative values.\r\n-  - If encode `integer` param is given as a number bigger than 1e+308: RangeError: Maximum call stack size exceeded.\r\n-  - If decode `value` param is given as a string or array wich characters or values are not included in the `base`: The return number will be a mess and incorrect.\r\n-  - If decode `value` param is given as a string somehow is too complex or too long: The return number will be `Infinity`.\r\n-  - If encode `auxArray` param is given a value: If you don't understand what you are doing, it will probably not work as expected.\r\n-  - If any value is assigned to any of the proto properties: The proto properties are read-only.\r\n\r\n## Credits\r\nThanks to [this stack overflow question](https://stackoverflow.com/questions/1337419/how-do-you-convert-numbers-between-different-bases-in-javascript/77164426#77164426) i got the inspiration to create useBase.\r\n\r\nI got the `splitPlus` function from [rootEnginear in this stack overflow answer](https://stackoverflow.com/a/71619350/8639520).\r\n\r\nTo make this `README` i used as reference [Axio's `README`](https://www.npmjs.com/package/axios).\r\n\r\n\r\n\r\n\r\n\r\n[Go back to top ↑](#usebaseencode-and-decode-numbers)","readmeFilename":"README.md"}