squidpony

Class Mnemonic

java.lang.Object

squidpony.Mnemonic

public class Mnemonic
extends java.lang.Object

A utility class to print (typically very large) numbers in a way that players can more-meaningfully tell them apart. It isn't that great for this task currently, but it can bi-directionally turn long values like -8798641734435409502 into Strings like nwihyayeetyoruehyazuetro. The advantage here is that nwihyayeetyoruehyazuetro is very different from protoezlebauyauzlutoatra, even though the numbers they are made from are harder to distinguish (-8798641734435409502 vs. -8032477240987739423, when using the default seed).
The constructor optionally takes a seed that can greatly change the generated mnemonics, which may be useful if mnemonic strings produced for some purpose should only be decipherable by that program or that play of the game. If no seed is given, this acts as if the seed is 1. Only 256 possible 3-letter sections are used with any given seed, but 431 sections are possible (hand-selected to avoid the likelihood of producing possibly-vulgar words). Two different seeds may use mostly-different selections of "syllable" sections, though a not-very-small amount of overlap in potential generated mnemonic strings must occur between any two seeds.
Created by Tommy Ettinger on 1/24/2018.

Field Summary

Fields

Modifier and Type	Field and Description
Arrangement<java.lang.String>	allAdjectives
Arrangement<java.lang.String>	allNouns
Arrangement<java.lang.String>	items

Constructor Summary

Constructors

Constructor and Description
Mnemonic() Default constructor for a Mnemonic generator; equivalent to new Mnemonic(1L), and probably a good choice unless you know you need different seeds.
Mnemonic(long seed) Constructor for a Mnemonic generator that allows a different seed to be chosen, which will alter the syllables produced by toMnemonic(long) and the words produced by toWordMnemonic(int, boolean) if you give the same numeric argument to differently-seeded Mnemonic generators.
Mnemonic(long seed, java.util.Collection<java.lang.String> adjectives, java.util.Collection<java.lang.String> nouns) Constructor that allows you to specify the adjective and noun collections used by toWordMnemonic(int, boolean) as well as a seed.
Mnemonic(long seed, java.lang.String[] adjectives, java.lang.String[] nouns) Constructor that allows you to specify the adjective and noun collections (given as arrays) used by toWordMnemonic(int, boolean) as well as a seed.

Method Summary

Modifier and Type	Method and Description
long	fromMnemonic(java.lang.String mnemonic) Takes a String produced by toMnemonic(long) or toMnemonic(long, boolean) and returns the long used to encode that gibberish String.
int	fromWordMnemonic(java.lang.String mnemonic) Takes a String phrase produced by toWordMnemonic(int, boolean) and returns the int used to encode that String.
java.lang.String	toMnemonic(long number) Given any long, generates a slightly-more-memorable gibberish phrase that can be decoded back to the original long with fromMnemonic(String).
java.lang.String	toMnemonic(long number, boolean capitalize) Given any long, generates a slightly-more-memorable gibberish phrase that can be decoded back to the original long with fromMnemonic(String).
java.lang.String	toWordMnemonic(int number, boolean capitalize) Given any int, generates a short phrase that can be decoded back to the original int with fromWordMnemonic(String).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

items

public final Arrangement<java.lang.String> items

allAdjectives

public final Arrangement<java.lang.String> allAdjectives

allNouns

public final Arrangement<java.lang.String> allNouns

Constructor Detail

Mnemonic

public Mnemonic()

Default constructor for a Mnemonic generator; equivalent to new Mnemonic(1L), and probably a good choice unless you know you need different seeds.
This depends on the current (at the time this Mnemonic is constructed) contents of Thesaurus.adjective and Thesaurus.noun, which can be modified, and if these contents aren't identical for two different Mnemonic objects (possibly constructed at different times, using different SquidLib versions), the Mnemonics will have different encoded and decoded forms. You can either save the key set from allAdjectives and allNouns and pass them to Mnemonic(long, Collection, Collection), or save the Thesaurus state altogether using Thesaurus.archiveCategories(), loading it before constructing any Mnemonics with Thesaurus.addArchivedCategories(String).

Mnemonic

public Mnemonic(long seed)

Constructor for a Mnemonic generator that allows a different seed to be chosen, which will alter the syllables produced by toMnemonic(long) and the words produced by toWordMnemonic(int, boolean) if you give the same numeric argument to differently-seeded Mnemonic generators. Unless you know you need this, you should probably use Mnemonic() to ensure that your text can be decoded.
This depends on the current (at the time this Mnemonic is constructed) contents of Thesaurus.adjective and Thesaurus.noun, which can be modified, and if these contents aren't identical for two different Mnemonic objects (possibly constructed at different times, using different SquidLib versions), the Mnemonics will have different encoded and decoded forms. You can either save the key set from allAdjectives and allNouns and pass them to Mnemonic(long, Collection, Collection), or save the Thesaurus state altogether using Thesaurus.archiveCategories(), loading it before constructing any Mnemonics with Thesaurus.addArchivedCategories(String).

Parameters:

seed - a long seed that will be used to randomize the syllables and words used.

Mnemonic

public Mnemonic(long seed,
                java.util.Collection<java.lang.String> adjectives,
                java.util.Collection<java.lang.String> nouns)

Constructor that allows you to specify the adjective and noun collections used by toWordMnemonic(int, boolean) as well as a seed. This should be useful when you want to enforce a stable relationship between word mnemonics produced by toWordMnemonic(int, boolean) and the int values they decode to with fromWordMnemonic(String), because the default can change if the adjective and noun collections in Thesaurus change. There should be a fairly large amount of unique adjectives and nouns; (long)adjectives.size() * nouns.size() * adjectives.size() * nouns.size() should be at least 0x80000000L (2147483648L), with case disregarded. If the total is less than that, not all possible ints can be encoded with toWordMnemonic(int, boolean). Having 216 adjectives and 216 nouns is enough for a rough target. Each word (adjectives and nouns alike) can have any characters in it except for space, since space is used during decoding to separate words.

Parameters:

seed - a long seed that will be used to randomize the syllables and words used.

adjectives - a Collection of unique Strings (case-insensitive) that will be used as adjectives

nouns - a Collection of unique Strings (case-insensitive) that will be used as nouns

Mnemonic

public Mnemonic(long seed,
                java.lang.String[] adjectives,
                java.lang.String[] nouns)

Constructor that allows you to specify the adjective and noun collections (given as arrays) used by toWordMnemonic(int, boolean) as well as a seed. This should be useful when you want to enforce a stable relationship between word mnemonics produced by toWordMnemonic(int, boolean) and the int values they decode to with fromWordMnemonic(String), because the default can change if the adjective and noun collections in Thesaurus change. There should be a fairly large amount of unique adjectives and nouns; (long)adjectives.length * nouns.length * adjectives.length * nouns.length should be at least 0x80000000L (2147483648L), with case disregarded. If the total is less than that, not all possible ints can be encoded with toWordMnemonic(int, boolean). Having 216 adjectives and 216 nouns is enough for a rough target. Each word (adjectives and nouns alike) can have any characters in it except for space, since space is used during decoding to separate words. You may want to use StringKit.split(String, String) with space or newline as the delimiter to get a String array from data containing space-separated words or data with one word per line. It's also possible to use String.split(String), which can use "\\s" to split on any whitespace.

Parameters:

seed - a long seed that will be used to randomize the syllables and words used.

adjectives - an array of unique Strings (case-insensitive) that will be used as adjectives

nouns - an array of unique Strings (case-insensitive) that will be used as nouns

Method Detail

toMnemonic

public java.lang.String toMnemonic(long number)

Given any long, generates a slightly-more-memorable gibberish phrase that can be decoded back to the original long with fromMnemonic(String). Examples of what this can produce are "noahritwimoesaidrubiotso" and "loanuiskohaimrunoizlupwi", generated by a Mnemonic with a seed of 1 from -3743983437744699304L and -8967299915041170097L, respectively. The Strings this returns are always 24 chars long, and contain only the letters a-z.

Parameters:

number - any long

Returns:

a 24-character String made of gibberish syllables

toMnemonic

public java.lang.String toMnemonic(long number,
                                   boolean capitalize)

Given any long, generates a slightly-more-memorable gibberish phrase that can be decoded back to the original long with fromMnemonic(String). Examples of what this can produce are "noahritwimoesaidrubiotso" and "loanuiskohaimrunoizlupwi", generated by a Mnemonic with a seed of 1 from -3743983437744699304L and -8967299915041170097L, respectively. The Strings this returns are always 24 chars long. If capitalize is true, then the first letter will be a capital letter from A-Z, all other letters will be a-z (including the first if capitalize is false).

Parameters:

number - any long

capitalize - if true, the initial letter of the returned mnemonic String will be capitalized

Returns:

a 24-character String made of gibberish syllables

fromMnemonic

public long fromMnemonic(java.lang.String mnemonic)

Takes a String produced by toMnemonic(long) or toMnemonic(long, boolean) and returns the long used to encode that gibberish String. This can't take just any String; if the given parameter isn't at least 24 characters long, this can throw an IndexOutOfBoundsException, and if it isn't made purely from the 3-char syllables toMnemonic() produces, it won't produce a meaningful result.

Parameters:

mnemonic - a gibberish String produced by toMnemonic(long) or toMnemonic(long, boolean)

Returns:

the long used to generate mnemonic originally

toWordMnemonic

public java.lang.String toWordMnemonic(int number,
                                       boolean capitalize)

Given any int, generates a short phrase that can be decoded back to the original int with fromWordMnemonic(String). Examples of what this can produce are "Mindful warriors and the pure torch" and "Dynastic earldom and the thousandfold bandit", generated by a Mnemonic with a seed of 1 from -587415991 and -1105099633, respectively. Those Strings were generated using the current state of Thesaurus and the adjectives and nouns it stores now, and if Thesaurus is added to over time, those Strings won't correspond to those ints any more. The Strings this returns vary in length. The words this uses by default use only the letters a-z and the single quote (with A-Z for the first character if capitalize is true), with space separating words. If you constructed this Mnemonic with adjective and noun collections or arrays, then this will use only those words and will still separate words with space (and it will capitalize the first char if capitalize is true).

Parameters:

number - any int

capitalize - if true, the initial letter of the returned mnemonic String will be capitalized

Returns:

a short phrase that will be uniquely related to number

fromWordMnemonic

public int fromWordMnemonic(java.lang.String mnemonic)

Takes a String phrase produced by toWordMnemonic(int, boolean) and returns the int used to encode that String. This can't take just any String; it must be produced by toWordMnemonic(int, boolean) to give a meaningful result.

Parameters:

mnemonic - a String phrase produced by toWordMnemonic(int, boolean)

Returns:

the int used to generate mnemonic originally