Skip to content

Latest commit

 

History

History
274 lines (203 loc) · 8.82 KB

API.md

File metadata and controls

274 lines (203 loc) · 8.82 KB
Raw

Table of Contents

AlphanumericEncoder

A class for encoding and decoding base 10 integers to a custom alphanumeric base representation.

Parameters

  • configOptions object? Optional object defining initial settings for the class (optional, default {allowLowerCaseDictionary:false,dictionary:'ABCDEFGHIJKLMNOPQRSTUVWXYZ'})

    • configOptions.allowLowerCaseDictionary boolean Whether or not to allow lower case letters in the dictionary (optional, default false)
    • configOptions.dictionary string Starting dictionary to use. Must contain only letters or numbers. Characters cannot be repeated. If allowLowerCaseDictionary = true, then lower case letters are not considered the same as upper case. (e.g. 'ABCabc' has 6 unique characters.) (optional, default 'ABCDEFGHIJKLMNOPQRSTUVWXYZ')

Examples

// Import into a project
const AlphanumericEncoder = require('alphanumeric-encoder')

const encoder = new AlphanumericEncoder()
// Import into a project
const AlphanumericEncoder = require('alphanumeric-encoder')

const encoder = new AlphanumericEncoder({ allowLowerCaseDictionary: true, dictionary: 'abcdEFGH' })
// Import into a project
const AlphanumericEncoder = require('alphanumeric-encoder')

const configOptions = { allowLowerCaseDictionary: true, dictionary: 'abcdEFGH' }
const encoder = new AlphanumericEncoder(configOptions)

dictionary

Returns or sets the current dictionary.

Parameters

  • newDictionary string (If setting) String of unique letters and numbers, in order, for the new dictionary

Examples

const encoder = new AlphanumericEncoder()

console.log(encoder.dictionary) // 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'

encoder.dictionary = 'ABCD'
console.log(encoder.dictionary) // 'ABCD'

encoder.dictionary = 'ABCDA' // Throws error because the letter 'A' is repeated
  • Throws RangeError if setting dictionary to null, undefined or empty string (i.e. '')
  • Throws RangeError if newDictionary contains a non-alphanumeric character
  • Throws RangeError if newDictionary has a repeating character

Returns string (If used as getter) The current dictionary in use

allowLowerCaseDictionary

Returns or sets a boolean value that determines whether the dictionary will allow lower case letters or not.

Parameters

  • isAllowed boolean (If setting). Accept truthy or falsy statements.

Examples

const encoder = new AlphanumericEncoder()
encoder.dictionary = 'abcdefg' // Default for `allowLowerCaseDictionary` is false
console.log(encoder.dictionary) // 'ABCDEFG'
const encoder = new AlphanumericEncoder()
encoder.allowLowerCaseDictionary = true
encoder.dictionary = 'ABCDefg'
console.log(encoder.dictionary) // 'ABCDefg'

Returns boolean (If used as getter)

resetDefaultDictionary

Reset the dictionary in use to the default.

Examples

const encoder = new AlphanumericEncoder()
console.log(encoder.dictionary) // 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
encoder.dictionary = 'ABCD'
console.log(encoder.dictionary) // 'ABCD'
encoder.resetDefaultDictionary()
console.log(encoder.dictionary) // 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'

Returns void

encode

Takes any number and converts it into a base (dictionary length) letter combo.

Parameters

  • integerToEncode number Base 10 integer. If passed a non-integer number, decimal values are truncated. Passing zero, negative numbers, or non-numbers will return undefined.

Examples

const encoder = new AlphanumericEncoder()
console.log(encoder.encode(5)) // 'E'
console.log(encoder.encode(48)) // 'AV'
console.log(encoder.encode(733)) // 'ABE'
encoder.dictionary = 'ABCD'
console.log(encoder.encode(5)) // 'AA'
console.log(encoder.encode(48)) // 'BCD'
console.log(encoder.encode(733)) // 'BCACA'
encoder.dictionary = 'DCBA'
console.log(encoder.encode(5)) // 'DD'
console.log(encoder.encode(48)) // 'CBA'
console.log(encoder.encode(733)) // 'CBDBD'
encoder.dictionary = 'ABC123'
console.log(encoder.encode(5)) // '2'
console.log(encoder.encode(48)) // 'AA3'
console.log(encoder.encode(733)) // 'CBBA'
console.log(encoder.encode('A')) // undefined
console.log(encoder.encode(null)) // undefined
console.log(encoder.encode(undefined)) // undefined
  • Throws RangeError if integerToEncode exceeds the maximum safe integer for Javascript (2^53 - 1 = 9007199254740991).

Returns (string | undefined) Dictionary encoded value. Returns undefined of passed negative numbers or NaN

decode

Takes any string and converts it into a base 10 integer based on the defined dictionary.

Parameters

  • stringToDecode string If passed a non-integer number, decimal values are truncated. Passing an empty string, null, or undefined will return undefined.

Examples

const encoder = new AlphanumericEncoder()
console.log(encoder.decode('A')) // 1
console.log(encoder.decode('AC')) // 29
console.log(encoder.decode('ANE')) // 1045
console.log(encoder.decode('a')) // undefined
console.log(encoder.decode(123)) // undefined
console.log(encoder.decode('A?')) // undefined
console.log(encoder.decode(null)) // undefined
console.log(encoder.decode(undefined)) // undefined
encoder.dictionary = 'ABCD'
console.log(encoder.decode('A')) // 1
console.log(encoder.decode('AC')) // 7
console.log(encoder.decode('ADBAC')) // 551
console.log(encoder.decode('ANE')) // undefined
  • Throws RangeError if the decoded integer exceeds the maximum safe integer for Javascript (2^53 - 1 = 9007199254740991).

Returns number Positive integer representation. If one of the characters is not present in the dictionary, it will return undefined.

deconstruct

Takes any string of letters and numbers and deconstructs it into an array of base 10 integers based on the defined dictionary.

Parameters

  • stringToDeconstruct string A string of letters and numbers (e.g. 'A7', 'AC22', '7C10F')

Examples

const encoder = new AlphanumericEncoder()
console.log(encoder.deconstruct('A')) // [1]
console.log(encoder.deconstruct('AC22')) // [29, 22]
console.log(encoder.deconstruct('C3ABC123EFGH456')) // [3, 3, 731, 123, 92126, 456]
console.log(encoder.deconstruct('A1aB2B')) // [1, 1, undefined, 2, 2]
console.log(encoder.deconstruct('7AC!23A1%')) // [7, undefined, 23, 1, 1, undefined]
console.log(encoder.deconstruct('')) // undefined
  • Throws Error if the dictionary contains a number as this function would be unable to differentiate between where a number and dictionary value.

Returns (Array<(number | undefined)> | undefined) An array of numbers. Characters not present in the dictionary are treated as letters and return undefined for that array value. Passing an empty string (''), null, or undefined will return undefined for the whole function.

Type: string