tilemapping

package
v0.2.19 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 25, 2026 License: GPL-3.0 Imports: 11 Imported by: 41

README

tilemapping - a library to interface between user-visible tiles such as "A" or "CH" and their 8-bit binary representations for word games.

Documentation

Index

Constants

View Source 
const (
	// MaxAlphabetSize should be below 64 so that a letterset can be a 64-bit int.
	MaxAlphabetSize = 62
	// ASCIIPlayedThrough is a somewhat user-friendly representation of a
	// played-through letter, used mostly for debug purposes.
	// Note that in order to actually be visible on a computer screen, we
	// should use `(`and `)` around letters already on a board.
	ASCIIPlayedThrough = '.'
	// BlankToken is the user-friendly representation of a blank.
	BlankToken = '?'
)

A "letter" or tile is internally represented by a byte. The 0 value is used to represent various things: - an empty space on the board - a blank on your rack - a "played-through" letter on the board, when used in the description of a play. The letter A is represented by 1, B by 2, ... all the way to 26, for the English alphabet, for example. A blank letter is the same but with the high bit set (0x80 | ml)

View Source 
const (
	BlankMask   = 0x80
	UnblankMask = (0x80 - 1)
)

Variables

View Source 
var CacheKeyPrefix = "letterdist:"

Functions

func CacheLoadFunc 

func CacheLoadFunc(cfg *config.Config, key string) (interface{}, error)

CacheLoadFunc is the function that loads an object into the global cache.

func ProbableLetterDistributionName added in v0.2.3 

func ProbableLetterDistributionName(lexname string) (string, error)

ProbableLetterDistributionName returns a letter distribution name given a lexicon name. It makes a best guess for the letter distribution, assuming that it would be the "standard" one for that lexicon.

func SortMW 

func SortMW(l MachineWord)

Types

type Bag 

type Bag struct {
	// contains filtered or unexported fields
}

A Bag is the bag o'tiles!

func NewBag 

func NewBag(ld *LetterDistribution, alph *TileMapping) *Bag

func (*Bag) Copy 

func (b *Bag) Copy() *Bag

Copy copies to a new bag and returns it. Note that the initialTiles are only shallowly copied. This is fine because we don't ever expect these to change after initialization.

func (*Bag) CopyFrom 

func (b *Bag) CopyFrom(other *Bag)

CopyFrom copies back the tiles from another bag into this bag. The caller of this function is responsible for ensuring `other` has the other structures we need! (letter distribution, etc). It should have been created from the Copy function above.

func (*Bag) Draw 

func (b *Bag) Draw(n int, ml []MachineLetter) error

Draw draws n random tiles from the bag. Shuffling is immaterial if fixedOrder is false. Returns the number of tiles actually drawn. This is a zero-alloc draw into the passed-in slice. NOTE: this function does not resize ml at all. It must be the correct size to allow tiles to fit in!

func (*Bag) DrawAtMost 

func (b *Bag) DrawAtMost(n int, ml []MachineLetter) int

DrawAtMost draws at most n tiles from the bag. It can draw fewer if there are fewer tiles than n, and even draw no tiles at all :o This is a zero-alloc draw into the passed-in slice.

func (*Bag) Exchange 

func (b *Bag) Exchange(letters []MachineLetter, ml []MachineLetter) error

Exchange exchanges the junk in your rack with new tiles.

func (*Bag) HasRack 

func (b *Bag) HasRack(letters []MachineLetter) bool

hasRack returns a boolean indicating whether the passed-in rack is in the bag, in its entirety.

func (*Bag) LetterDistribution 

func (b *Bag) LetterDistribution() *LetterDistribution

func (*Bag) Peek 

func (b *Bag) Peek() []MachineLetter

Peek returns a copy of the tiles array.

func (*Bag) PeekMap 

func (b *Bag) PeekMap() []uint8

func (*Bag) PutBack 

func (b *Bag) PutBack(letters []MachineLetter)

PutBack puts the tiles back in the bag, and shuffles the bag.

func (*Bag) Redraw 

func (b *Bag) Redraw(currentRack []MachineLetter, ml []MachineLetter) int

Redraw is basically a do-over; throw the current rack in the bag and draw a new rack.

func (*Bag) Refill 

func (b *Bag) Refill()

Refill refills the bag.

func (*Bag) RemoveTiles 

func (b *Bag) RemoveTiles(tiles []MachineLetter) error

RemoveTiles removes the given tiles from the bag, and returns an error if it can't.

func (*Bag) SetFixedOrder 

func (b *Bag) SetFixedOrder(f bool)

SetFixedOrder makes the bag drawing algorithm repeatable if the bag is copied before drawing. This can be useful for more accurate Monte Carlo sims. It is extremely recommended to do a shuffle first if you want to use fixed order.

func (*Bag) SetRNG added in v0.2.17 

func (b *Bag) SetRNG(rng *frand.RNG)

SetRNG sets a custom RNG for deterministic randomness. This makes the bag's shuffles and draws fully deterministic based on the RNG's seed.

func (*Bag) Shuffle 

func (b *Bag) Shuffle()

Shuffle shuffles the bag.

func (*Bag) SwapTile 

func (b *Bag) SwapTile(idx1, idx2 int)

SwapTile swaps the tiles in the bag at the two given indices. This is only used when we want to control what tiles a player should draw, for pre-endgames, simulations, and related purposes. It very likely should be used in concert with the "fixedOrder" setting.

func (*Bag) Tiles 

func (b *Bag) Tiles() []MachineLetter

Tiles returns the actual tile array. Careful when using this!

func (*Bag) TilesRemaining 

func (b *Bag) TilesRemaining() int

type LetterDistribution 

type LetterDistribution struct {
	Vowels []MachineLetter

	Name string
	// contains filtered or unexported fields
}

LetterDistribution encodes the tile distribution for the relevant game.

func EnglishLetterDistribution 

func EnglishLetterDistribution(cfg *config.Config) (*LetterDistribution, error)

EnglishLetterDistribution returns the English letter distribution.

func GetDistribution 

func GetDistribution(cfg *config.Config, name string) (*LetterDistribution, error)

GetDistribution loads a named letter distribution from the cache or from a file. The Name field is set when the distribution is first loaded into the cache (via CacheLoadFunc -> NamedLetterDistribution), so callers receive a fully initialized object. We intentionally do not modify the returned object here to avoid data races when multiple goroutines access the same cached instance.

func NamedLetterDistribution 

func NamedLetterDistribution(cfg *config.Config, name string) (*LetterDistribution, error)

NamedLetterDistribution loads a letter distribution by name.

func ProbableLetterDistribution added in v0.1.7 

func ProbableLetterDistribution(cfg *config.Config, lexname string) (*LetterDistribution, error)

ProbableLetterDistribution returns a letter distribution given a lexicon name. It makes a best guess for the letter distribution, assuming that it would be the "standard" one for that lexicon.

func ScanLetterDistribution 

func ScanLetterDistribution(data io.Reader) (*LetterDistribution, error)

func (*LetterDistribution) Distribution 

func (ld *LetterDistribution) Distribution() []uint8

func (*LetterDistribution) MakeBag 

func (ld *LetterDistribution) MakeBag() *Bag

MakeBag returns a bag of tiles.

func (*LetterDistribution) NumTotalLetters 

func (ld *LetterDistribution) NumTotalLetters() uint

func (*LetterDistribution) Score 

func (ld *LetterDistribution) Score(ml MachineLetter) int

Score gives the score of the given machine letter. This is used by the move generator to score plays more rapidly than looking up a map.

func (*LetterDistribution) TileMapping 

func (d *LetterDistribution) TileMapping() *TileMapping

func (*LetterDistribution) WordScore 

func (ld *LetterDistribution) WordScore(mw MachineWord) int

Score returns the score of this word given the ld.

type LetterSet 

type LetterSet uint64

LetterSet is a bit mask of acceptable letters, with indices from 0 to the maximum alphabet size.

type MachineLetter 

type MachineLetter byte

MachineLetter is a machine-only representation of a letter. It represents a signed integer; negative for blank letters, 0 for blanks, positive for regular letters.

func ToMachineLetters 

func ToMachineLetters(word string, rm *TileMapping) ([]MachineLetter, error)

ToMachineLetters creates an array of MachineLetters from the given string.

func (MachineLetter) Blank 

func (ml MachineLetter) Blank() MachineLetter

Blank turns the machine letter into its blank version

func (MachineLetter) IntrinsicTileIdx 

func (ml MachineLetter) IntrinsicTileIdx() MachineLetter

IntrinsicTileIdx returns the index that this tile would have in a rack's LetArr.

func (MachineLetter) IsBlanked 

func (ml MachineLetter) IsBlanked() bool

IsBlanked returns true if the machine letter is a designated blank letter.

func (MachineLetter) IsPlayedTile 

func (ml MachineLetter) IsPlayedTile() bool

IsPlayedTile returns true if this represents a tile that was actually played on the board. It has to be an assigned blank or a letter, not a played-through-marker.

func (MachineLetter) IsVowel 

func (ml MachineLetter) IsVowel(ld *LetterDistribution) bool

func (MachineLetter) Unblank 

func (ml MachineLetter) Unblank() MachineLetter

Unblank turns the machine letter into its non-blank version (if it's a blanked letter)

func (MachineLetter) UserVisible 

func (ml MachineLetter) UserVisible(rm *TileMapping, zeroForPlayedThrough bool) string

UserVisible turns the passed-in machine letter into a user-visible string.

type MachineWord 

type MachineWord []MachineLetter

func FromByteArr 

func FromByteArr(bts []byte) MachineWord

func Leave 

func Leave(rack MachineWord, tilesToRemove MachineWord, zeroIsPlaythrough bool) (MachineWord, error)

Leave calculates the tiles remaining in the rack after removing the specified tiles.

Parameters:

  • rack: The current rack tiles
  • tilesToRemove: The tiles to remove from the rack
  • zeroIsPlaythrough: If true, tile 0 in tilesToRemove represents a play-through marker (a tile already on the board being played through) and won't be removed from the rack. If false, tile 0 is treated as a regular blank tile and will be removed from the rack.

Returns the remaining tiles (leave) after removal, or an error if the rack doesn't contain the tiles to be removed.

func ToMachineWord 

func ToMachineWord(word string, tm *TileMapping) (MachineWord, error)

func (MachineWord) Score 

func (mw MachineWord) Score(ld *LetterDistribution) int

Score returns the score of this word given the ld.

func (MachineWord) ToByteArr 

func (mw MachineWord) ToByteArr() []byte

Convert the MachineLetter array into a byte array. For now, wastefully allocate a byte array, but maybe we can use the unsafe package in the future.

func (MachineWord) UserVisible 

func (mw MachineWord) UserVisible(rm *TileMapping) string

UserVisible turns the passed-in machine word into a user-visible string.

func (MachineWord) UserVisiblePlayedTiles 

func (mw MachineWord) UserVisiblePlayedTiles(rm *TileMapping) string

UserVisiblePlayedTiles turns the passed-in machine word into a user-visible string. It assumes that the MachineWord represents played tiles and not just tiles on a rack, so it uses the PlayedThrough character for 0.

type Rack 

type Rack struct {
	// letArr is an array of letter codes from 0 to alphabet.NumLetters.
	// The blank goes at 0.
	LetArr []int
	// contains filtered or unexported fields
}

Rack is a machine-friendly representation of a user's rack.

func NewRack 

func NewRack(alph *TileMapping) *Rack

NewRack creates a brand new rack structure with an alphabet.

func RackFromString 

func RackFromString(rack string, a *TileMapping) *Rack

RackFromString creates a Rack from a string and an alphabet

func (*Rack) Add 

func (r *Rack) Add(letter MachineLetter)

func (*Rack) Alphabet 

func (r *Rack) Alphabet() *TileMapping

func (*Rack) Clear 

func (r *Rack) Clear()

func (*Rack) Copy 

func (r *Rack) Copy() *Rack

Copy returns a deep copy of this rack

func (*Rack) CopyFrom 

func (r *Rack) CopyFrom(other *Rack)

func (*Rack) CountOf 

func (r *Rack) CountOf(letter MachineLetter) int

func (*Rack) Empty 

func (r *Rack) Empty() bool

func (*Rack) Has 

func (r *Rack) Has(letter MachineLetter) bool

func (*Rack) NoAllocTilesOn 

func (r *Rack) NoAllocTilesOn(letters []MachineLetter) int

NoAllocTilesOn places the tiles in the passed-in slice, and returns the number of letters

func (*Rack) NumTiles 

func (r *Rack) NumTiles() uint8

NumTiles returns the current number of tiles on this rack.

func (*Rack) ScoreOn 

func (r *Rack) ScoreOn(ld *LetterDistribution) int

ScoreOn returns the total score of the tiles on this rack.

func (*Rack) Set 

func (r *Rack) Set(mls []MachineLetter)

Set sets the rack from a list of machine letters

func (*Rack) String 

func (r *Rack) String() string

String returns a user-visible version of this rack.

func (*Rack) Take 

func (r *Rack) Take(letter MachineLetter)

func (*Rack) TilesOn 

func (r *Rack) TilesOn() MachineWord

TilesOn returns the MachineLetters of the rack's current tiles. It is alphabetized.

type TileMapping 

type TileMapping struct {
	// contains filtered or unexported fields
}

A TileMapping contains the structures needed to map a user-visible "rune", like the letter B, into its "MachineLetter" counterpart (for example, MachineLetter(2) in the english-alphabet), and vice-versa.

func (*TileMapping) Init 

func (rm *TileMapping) Init()

Init initializes the alphabet data structures

func (*TileMapping) Letter 

func (rm *TileMapping) Letter(b MachineLetter) string

Letter returns the letter that this position in the alphabet corresponds to.

func (*TileMapping) NumLetters 

func (rm *TileMapping) NumLetters() uint8

NumLetters returns the number of letters in this alphabet. It includes the blank.

func (*TileMapping) Reconcile 

func (rm *TileMapping) Reconcile(letters []string)

Reconcile will take a populated alphabet, sort the glyphs, and re-index the numbers.

func (*TileMapping) Val 

func (rm *TileMapping) Val(s string) (MachineLetter, error)

Val returns the 'value' of this rune in the alphabet. Takes into account blanks (lowercase letters).

func (*TileMapping) Vals 

func (rm *TileMapping) Vals() map[string]MachineLetter

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.