regina::Perm< 5 > Class Template Reference
Mathematical Support

Represents a permutation of {0,1,2,3,4}. More...

`#include <maths/spec/perm5.h>`

## Public Types

typedef int | Index
| Denotes a native signed integer type large enough to count all permutations on five elements. More...
typedef uint16_t | Code
| Indicates the native unsigned integer type used to store the internal permutation code. More...

## Public Member Functions

| Perm ()
| Creates the identity permutation. More...
| Perm (int a, int b)
| Creates the transposition of a and b. More...
| Perm (int a, int b, int c, int d, int e)
| Creates a permutation mapping (0,1,2,3,4) to (a,b,c,d,e) respectively. More...
| Perm (const int *image)
| Creates a permutation mapping i to image[i] for each i = 0,1,2,3,4. More...
| Perm (const int *a, const int *b)
| Creates a permutation mapping (a[0], ..., a[4]) to (b[0], ..., b[4]) respectively. More...
| Perm (int a0, int a1, int b0, int b1, int c0, int c1, int d0, int d1, int e0, int e1)
| Creates a permutation mapping (a0,b0,c0,d0,e0) to (a1,b1,c1,d1,e1) respectively. More...
| Perm (const Perm< 5 > &cloneMe)
| Creates a permutation that is a clone of the given permutation. More...
Code | permCode () const
| Returns the internal code representing this permutation. More...
void | setPermCode (Code newCode)
| Sets this permutation to that represented by the given internal code. More...
Perm< 5 > & | operator= (const Perm< 5 > &cloneMe)
| Sets this permutation to be equal to the given permutation. More...
Perm< 5 > | operator* (const Perm< 5 > &q) const
| Returns the composition of this permutation with the given permutation. More...
Perm< 5 > | inverse () const
| Finds the inverse of this permutation. More...
Perm< 5 > | reverse () const
| Finds the reverse of this permutation. More...
int | sign () const
| Determines the sign of this permutation. More...
REGINA_INLINE_REQUIRED int | operator[] (int source) const
| Determines the image of the given integer under this permutation. More...
int | preImageOf (int image) const
| Determines the preimage of the given integer under this permutation. More...
bool | operator== (const Perm< 5 > &other) const
| Determines if this is equal to the given permutation. More...
bool | operator!= (const Perm< 5 > &other) const
| Determines if this differs from the given permutation. More...
int | compareWith (const Perm< 5 > &other) const
| Lexicographically compares the images of (0,1,2,3,4) under this and the given permutation. More...
bool | isIdentity () const
| Determines if this is the identity permutation. More...
Index | index () const
| Returns the lexicographical index of this permutation. More...
std::string | str () const
| Returns a string representation of this permutation. More...
std::string | trunc (unsigned len) const
| Returns a prefix of the string representation of this permutation, containing only the images of the first len integers. More...
std::string | trunc2 () const
| Returns a string representation of this permutation with only the images of 0 and 1. More...
std::string | trunc3 () const
| Returns a string representation of this permutation with only the images of 0, 1 and 2. More...
std::string | trunc4 () const
| Returns a string representation of this permutation with only the images of 0, 1, 2 and 3. More...
void | clear (unsigned from)
| Resets the images of all integers from from onwards to the identity map. More...
int | S5Index () const
| Returns the index of this permutation in the Perm<5>::S5 array. More...
int | SnIndex () const
| Returns the index of this permutation in the Perm<5>::S5 array. More...
int | orderedS5Index () const
| Returns the index of this permutation in the Perm<5>::orderedS5 array. More...
int | orderedSnIndex () const
| Returns the index of this permutation in the Perm<5>::orderedS5 array. More...

## Static Public Member Functions

static Perm< 5 > | fromPermCode (Code newCode)
| Creates a permutation from the given internal code. More...
static bool | isPermCode (Code newCode)
| Determines whether the given integer is a valid internal permutation code. More...
static Perm | atIndex (Index i)
| Returns the ith permutation on five elements, where permutations are numbered lexicographically beginning at 0. More...
static Perm | rand ()
| Returns a random permutation on five elements. More...
template<int k>
static Perm< 5 > | extend (Perm< k > p)
| Extends a k-element permutation to a 5-element permutation, where 2 ≤ k < 5. More...
template<int k>
static Perm< 5 > | contract (Perm< k > p)
| Restricts a k-element permutation to an 5-element permutation, where k > 5. More...

## Static Public Attributes

static const Index | nPerms = 120
| The total number of permutations on five elements. More...
static const Index | nPerms_1 = 24
| The total number of permutations on four elements. More...
static const int | imageBits = 3
| Indicates the number of bits used by the permutation code to store the image of a single integer. More...
static const Perm< 5 > | S5 [120]
| Contains all possible permutations of five elements. More...
static const Perm< 5 > * | Sn
| A dimension-agnostic alias for Perm<5>::S5. More...
static const Perm< 5 > | orderedS5 [120]
| Contains all possible permutations of five elements in lexicographical order. More...
static const Perm< 5 > * | orderedSn
| A dimension-agnostic alias for Perm<5>::orderedS5. More...
static const unsigned | invS5 [120]
| Contains the inverses of the permutations in the array S5. More...
static const unsigned * | invSn
| A dimension-agnostic alias for Perm<5>::invS5. More...
static const Perm< 5 > | S4 [24]
| Contains all possible permutations of four elements. More...
static const Perm< 5 > * | Sn_1
| A dimension-agnostic alias for Perm<5>::S4. More...
static const Perm< 5 > | orderedS4 [24]
| Contains all possible permutations of four elements in lexicographical order. More...
static const Perm< 5 > | S3 [6]
| Contains all possible permutations of three elements. More...
static const Perm< 5 > | orderedS3 [6]
| Contains all possible permutations of three elements in lexicographical order. More...
static const Perm< 5 > | S2 [2]
| Contains all possible permutations of two elements. More...

## Detailed Description

### template<>
class regina::Perm< 5 >

Represents a permutation of {0,1,2,3,4}.

This is a specialisation of the generic Perm template: it is highly optimised, and also offers some additional functionality. Amongst other things, this permutation class is used to specify how simplices of a 4-manifold triangulation are glued together.

As with all Perm template classes, these objects are small enough to pass about by value instead of by reference.

Each permutation has an internal code, which is a single native integer that is sufficient to reconstruct the permutation. Thus the internal code may be a useful means for passing permutation objects to and from the engine. For Perm<5>, the internal code follows the general scheme used for Perm<n>: the lowest three bits represent the image of 0, the next lowest three bits represent the image of 1 and so on. See the generic Perm template for further details.

To use this class, simply include the main permutation header maths/perm.h.

Python:
  Since Python does not support templates, this class is made available under the name Perm5.

## Member Typedef Documentation

## Code

typedef uint16_t regina::Perm< 5 >::Code

Indicates the native unsigned integer type used to store the internal permutation code.

## Index

typedef int regina::Perm< 5 >::Index

Denotes a native signed integer type large enough to count all permutations on five elements.

In other words, this is a native signed integer type large enough to store (5!).

## Constructor & Destructor Documentation

## Perm() [1/7]

regina::Perm< 5 >::Perm | ( |  | ) |

inline

Creates the identity permutation.

## Perm() [2/7]

regina::Perm< 5 >::Perm | ( | int | a,
|  | int | b
| ) |  |

inline

Creates the transposition of a and b.

Note that a and b need not be distinct.

Precondition
  a and b are in {0,1,2,3,4}.

Parameters

  a | the element to switch with b.
  b | the element to switch with a.

## Perm() [3/7]

regina::Perm< 5 >::Perm | ( | int | a,
|  | int | b,
|  | int | c,
|  | int | d,
|  | int | e
| ) |  |

inline

Creates a permutation mapping (0,1,2,3,4) to (a,b,c,d,e) respectively.

Precondition
  {a,b,c,d,e} = {0,1,2,3,4}.

Parameters

  a | the desired image of 0.
  b | the desired image of 1.
  c | the desired image of 2.
  d | the desired image of 3.
  e | the desired image of 4.

## Perm() [4/7]

regina::Perm< 5 >::Perm | ( | const int * | image | ) |

inline

Creates a permutation mapping i to image[i] for each i = 0,1,2,3,4.

Precondition
  The array image contains five elements, which are 0, 1, 2, 3 and 4 in some order.

Python:
  Not present.

Parameters

  image | the array of images.

## Perm() [5/7]

regina::Perm< 5 >::Perm | ( | const int * | a,
|  | const int * | b
| ) |  |

inline

Creates a permutation mapping (a[0], ..., a[4]) to (b[0], ..., b[4]) respectively.

Precondition
  Both arrays a and b contain 5 elements, which are 0,...,4 in some order.

Python:
  Not present.

Parameters

  a | the array of preimages; this must have length 5.
  b | the corresponding array of images; this must also have length 5.

## Perm() [6/7]

regina::Perm< 5 >::Perm | ( | int | a0,
|  | int | a1,
|  | int | b0,
|  | int | b1,
|  | int | c0,
|  | int | c1,
|  | int | d0,
|  | int | d1,
|  | int | e0,
|  | int | e1
| ) |  |

inline

Creates a permutation mapping (a0,b0,c0,d0,e0) to (a1,b1,c1,d1,e1) respectively.

Precondition
  {a0,b0,c0,d0,e0} = {a1,b1,c1,d1,e1} = {0,1,2,3,4}.

Parameters

  a0 | the desired preimage of a1.
  b0 | the desired preimage of b1.
  c0 | the desired preimage of c1.
  d0 | the desired preimage of d1.
  e0 | the desired preimage of e1.
  a1 | the desired image of a0.
  b1 | the desired image of b0.
  c1 | the desired image of c0.
  d1 | the desired image of d0.
  e1 | the desired image of e0.

## Perm() [7/7]

regina::Perm< 5 >::Perm | ( | const Perm< 5 > & | cloneMe | ) |

inline

Creates a permutation that is a clone of the given permutation.

Parameters

  cloneMe | the permutation to clone.

## Member Function Documentation

## atIndex()

Perm< 5 > regina::Perm< 5 >::atIndex | ( | Index | i | ) |

inline static

Returns the ith permutation on five elements, where permutations are numbered lexicographically beginning at 0.

Lexicographical ordering treats each permutation p as the 5-tuple (p[0], p[1], p[2], p[3], p[4]).

The return value will be identical to orderedS5[i].

Parameters

  i | the lexicographical index of the permutation; this must be between 0 and 119 inclusive.

Returns
  the ith permutation.

## clear()

void regina::Perm< 5 >::clear | ( | unsigned | from | ) |

Resets the images of all integers from from onwards to the identity map.

Specifically, for each i in the range from,...,4, this routine will ensure that `image[i] == i`. The images of 0,1,...,from-1 will not be altered.

Precondition
  The images of from,...,4 are exactly from,...,4, but possibly in a different order.

Parameters

  from | the first integer whose image should be reset. This must be between 0 and 5 inclusive.

## compareWith()

int regina::Perm< 5 >::compareWith | ( | const Perm< 5 > & | other | ) | const

Lexicographically compares the images of (0,1,2,3,4) under this and the given permutation.

Parameters

  other | the permutation with which to compare this.

Returns
  -1 if this permutation produces a smaller image, 0 if the permutations are equal and 1 if this permutation produces a greater image.

## contract()

template<int k>

static Perm<5> regina::Perm< 5 >::contract | ( | Perm< k > | p | ) |

static

Restricts a k-element permutation to an 5-element permutation, where k > 5.

The resulting permutation will map 0,...,3 to their respective images under p, and will ignore the "unused" images p[5],...,p[k-1].

Precondition
  The given permutation maps 0,...,4 to 0,...,4 in some order.

Template Parameters

  k | the number of elements for the input permutation; this must be strictly greater than 5.

Parameters

  p | a permutation on k elements.

Returns
  the same permutation restricted to a permutation on 5 elements.

## extend()

template<int k>

static Perm<5> regina::Perm< 5 >::extend | ( | Perm< k > | p | ) |

static

Extends a k-element permutation to a 5-element permutation, where 2 ≤ k < 5.

The resulting permutation will map 0,...,k-1 to their respective images under p, and will map the "unused" elements k,...,4 to themselves.

Template Parameters

  k | the number of elements for the input permutation; this must be 2, 3 or 4.

Parameters

  p | a permutation on k elements.

Returns
  the same permutation expressed as a permutation on five elements.

## fromPermCode()

Perm< 5 > regina::Perm< 5 >::fromPermCode | ( | Code | newCode | ) |

inline static

Creates a permutation from the given internal code.

Precondition
  the given code is a valid permutation code; see isPermCode() for details.

Parameters

  newCode | the internal code for the new permutation.

Returns
  the permutation reprsented by the given internal code.

## index()

Perm< 5 >::Index regina::Perm< 5 >::index | ( |  | ) | const

inline

Returns the lexicographical index of this permutation.

This indicates where this permutation sits within a full lexicographical ordering of all 5! permutations on five elements.

Lexicographical ordering treats each permutation p as the 5-tuple (p[0], p[1], p[2], p[3], p[4]). In particular, the identity permutation has index 0, and the "reverse" permutation (which maps each i to 4-i) has index 119 = 5!-1.

This routine is identical to orderedS5Index().

Returns
  the index of this permutation, which will be between 0 and 119 inclusive.

## inverse()

Perm< 5 > regina::Perm< 5 >::inverse | ( |  | ) | const

inline

Finds the inverse of this permutation.

Returns
  the inverse of this permutation.

## isIdentity()

bool regina::Perm< 5 >::isIdentity | ( |  | ) | const

inline

Determines if this is the identity permutation.

This is true if and only if each of 0, 1, 2, 3 and 4 is mapped to itself.

Returns
  `true` if and only if this is the identity permutation.

## isPermCode()

static bool regina::Perm< 5 >::isPermCode | ( | Code | newCode | ) |

static

Determines whether the given integer is a valid internal permutation code.

Valid permutation codes can be passed to setPermCode() or fromPermCode(), and are returned by permCode().

Returns
  `true` if and only if the given code is a valid internal permutation code.

## operator!=()

bool regina::Perm< 5 >::operator!= | ( | const Perm< 5 > & | other | ) | const

inline

Determines if this differs from the given permutation.

This is true if and only if the two permutations have different images for at least one of 0, 1, 2, 3 or 4.

Parameters

  other | the permutation with which to compare this.

Returns
  `true` if and only if this and the given permutation differ.

## operator*()

Perm< 5 > regina::Perm< 5 >::operator* | ( | const Perm< 5 > & | q | ) | const

inline

Returns the composition of this permutation with the given permutation.

If this permutation is p, the resulting permutation will be p o q, satisfying `(p*q)[x] == p[q[x]]`.

Parameters

  q | the permutation with which to compose this.

Returns
  the composition of both permutations.

## operator=()

Perm< 5 > & regina::Perm< 5 >::operator= | ( | const Perm< 5 > & | cloneMe | ) |

inline

Sets this permutation to be equal to the given permutation.

Parameters

  cloneMe | the permutation whose value will be assigned to this permutation.

Returns
  a reference to this permutation.

## operator==()

bool regina::Perm< 5 >::operator== | ( | const Perm< 5 > & | other | ) | const

inline

Determines if this is equal to the given permutation.

This is true if and only if both permutations have the same images for 0, 1, 2, 3 and 4.

Parameters

  other | the permutation with which to compare this.

Returns
  `true` if and only if this and the given permutation are equal.

## operator[]()

int regina::Perm< 5 >::operator[] | ( | int | source | ) | const

inline

Determines the image of the given integer under this permutation.

Parameters

  source | the integer whose image we wish to find. This should be between 0 and 4 inclusive.

Returns
  the image of source.

## orderedS5Index()

int regina::Perm< 5 >::orderedS5Index | ( |  | ) | const

Returns the index of this permutation in the Perm<5>::orderedS5 array.

Returns
  the index i for which this permutation is equal to Perm<5>::orderedS5[i]. This will be between 0 and 119 inclusive.

Author
  Ryan Budney

## orderedSnIndex()

int regina::Perm< 5 >::orderedSnIndex | ( |  | ) | const

inline

Returns the index of this permutation in the Perm<5>::orderedS5 array.

This is a dimension-agnostic alias for orderedS5Index().

Returns
  the index i for which this permutation is equal to Perm<5>::orderedS5[i]. This will be between 0 and 119 inclusive.

## permCode()

Perm< 5 >::Code regina::Perm< 5 >::permCode | ( |  | ) | const

inline

Returns the internal code representing this permutation.

Note that the internal code is sufficient to reproduce the entire permutation.

The code returned will be a valid permutation code as determined by isPermCode().

Returns
  the internal code.

## preImageOf()

int regina::Perm< 5 >::preImageOf | ( | int | image | ) | const

inline

Determines the preimage of the given integer under this permutation.

Parameters

  image | the integer whose preimage we wish to find. This should be between 0 and 4 inclusive.

Returns
  the preimage of image.

## rand()

Perm< 5 > regina::Perm< 5 >::rand | ( |  | ) |

inline static

Returns a random permutation on five elements.

All permutations are returned with equal probability.

The implementation uses the C standard ::rand() function for its random number generation.

Returns
  a random permutation.

## reverse()

Perm< 5 > regina::Perm< 5 >::reverse | ( |  | ) | const

inline

Finds the reverse of this permutation.

Here reverse means that we reverse the images of 0,...,4. In other words, if permutation q is the reverse of p, then `p[i] == q[4 - i]` for all i.

## S5Index()

int regina::Perm< 5 >::S5Index | ( |  | ) | const

Returns the index of this permutation in the Perm<5>::S5 array.

Returns
  the index i for which this permutation is equal to Perm<5>::S5[i]. This will be between 0 and 119 inclusive.

Author
  Ryan Budney

## setPermCode()

void regina::Perm< 5 >::setPermCode | ( | Code | newCode | ) |

inline

Sets this permutation to that represented by the given internal code.

Precondition
  the given code is a valid permutation code; see isPermCode() for details.

Parameters

  newCode | the internal code that will determine the new value of this permutation.

## sign()

int regina::Perm< 5 >::sign | ( |  | ) | const

Determines the sign of this permutation.

Returns
  1 if this permutation is even, or -1 if this permutation is odd.

## SnIndex()

int regina::Perm< 5 >::SnIndex | ( |  | ) | const

inline

Returns the index of this permutation in the Perm<5>::S5 array.

This is a dimension-agnostic alias for S5Index().

Returns
  the index i for which this permutation is equal to Perm<5>::S5[i]. This will be between 0 and 119 inclusive.

## str()

std::string regina::Perm< 5 >::str | ( |  | ) | const

Returns a string representation of this permutation.

The representation will consist of five adjacent digits representing the images of 0, 1, 2, 3 and 4 respectively. An example of a string representation is `30421`.

Returns
  a string representation of this permutation.

## trunc()

std::string regina::Perm< 5 >::trunc | ( | unsigned | len | ) | const

Returns a prefix of the string representation of this permutation, containing only the images of the first len integers.

Parameters

  len | the length of the prefix required; this must be between 0 and 5 inclusive.

Returns
  the corresponding prefix of the string representation of this permutation.

## trunc2()

std::string regina::Perm< 5 >::trunc2 | ( |  | ) | const

Returns a string representation of this permutation with only the images of 0 and 1.

The resulting string will therefore have length two.

Returns
  a truncated string representation of this permutation.

## trunc3()

std::string regina::Perm< 5 >::trunc3 | ( |  | ) | const

Returns a string representation of this permutation with only the images of 0, 1 and 2.

The resulting string will therefore have length three.

Returns
  a truncated string representation of this permutation.

## trunc4()

std::string regina::Perm< 5 >::trunc4 | ( |  | ) | const

Returns a string representation of this permutation with only the images of 0, 1, 2 and 3.

The resulting string will therefore have length four.

Returns
  a truncated string representation of this permutation.

## Member Data Documentation

## imageBits

const int regina::Perm< 5 >::imageBits = 3

static

Indicates the number of bits used by the permutation code to store the image of a single integer.

The full permutation code packs 5 such images together, and so uses 5 * imageBits bits in total.

## invS5

const unsigned regina::Perm< 5 >::invS5[120]

static

Contains the inverses of the permutations in the array S5.

Specifically, the inverse of permutation `S5[i]` is the permutation `S5[ invS5[i] ]`.

## invSn

const unsigned* regina::Perm< 5 >::invSn

static

A dimension-agnostic alias for Perm<5>::invS5.

In general, for each K the class PermK will define an alias invSn that references the list of all permutations PermK::invSK.

## nPerms

const Index regina::Perm< 5 >::nPerms = 120

static

The total number of permutations on five elements.

This is the size of the array Sn.

## nPerms_1

const Index regina::Perm< 5 >::nPerms_1 = 24

static

The total number of permutations on four elements.

This is the size of the array Sn_1.

## orderedS3

const Perm<5> regina::Perm< 5 >::orderedS3[6]

static

Contains all possible permutations of three elements in lexicographical order.

In each permutation, 3 maps to 3 and 4 maps to 4.

## orderedS4

const Perm<5> regina::Perm< 5 >::orderedS4[24]

static

Contains all possible permutations of four elements in lexicographical order.

In each permutation, 4 maps to 4.

## orderedS5

const Perm<5> regina::Perm< 5 >::orderedS5[120]

static

Contains all possible permutations of five elements in lexicographical order.

## orderedSn

const Perm<5>* regina::Perm< 5 >::orderedSn

static

A dimension-agnostic alias for Perm<5>::orderedS5.

In general, for each K the class PermK will define an alias orderedSn that references the list of all permutations PermK::orderedSK.

## S2

const Perm<5> regina::Perm< 5 >::S2[2]

static

Contains all possible permutations of two elements.

In each permutation, 2 maps to 2, 3 maps to 3, and 4 maps to 4.

The permutations with even indices in the array are the even permutations, and those with odd indices in the array are the odd permutations.

For all permutation classes (Perm<4>, Perm<5> and so on), the S2 array stores the same permutations in the same order (but of course using different data types).

Note that these permutations are already in lexicographical order.

## S3

const Perm<5> regina::Perm< 5 >::S3[6]

static

Contains all possible permutations of three elements.

In each permutation, 3 maps to 3 and 4 maps to 4.

The permutations with even indices in the array are the even permutations, and those with odd indices in the array are the odd permutations.

For all permutation classes (Perm<4>, Perm<5> and so on), the S3 array stores the same permutations in the same order (but of course using different data types).

Note that the permutations are not necessarily in lexicographical order. For the corresponding inverse array, see Perm<3>::invS3.

## S4

const Perm<5> regina::Perm< 5 >::S4[24]

static

Contains all possible permutations of four elements.

In each permutation, 4 maps to 4.

The permutations with even indices in the array are the even permutations, and those with odd indices in the array are the odd permutations.

For all permutation classes (Perm<4>, Perm<5> and so on), the S4 array stores the same permutations in the same order (but of course using different data types).

Note that the permutations are not necessarily in lexicographical order. For the corresponding inverse array, see Perm<4>::invS4.

## S5

const Perm<5> regina::Perm< 5 >::S5[120]

static

Contains all possible permutations of five elements.

The permutations with even indices in the array are the even permutations, and those with odd indices in the array are the odd permutations.

Note that the permutations are not necessarily in lexicographical order.

## Sn

const Perm<5>* regina::Perm< 5 >::Sn

static

A dimension-agnostic alias for Perm<5>::S5.

In general, for each K the class PermK will define an alias Sn that references the list of all permutations PermK::SK.

## Sn_1

const Perm<5>* regina::Perm< 5 >::Sn_1

static

A dimension-agnostic alias for Perm<5>::S4.

In general, for each K the class PermK will define an alias Sn_1 that references the list of all permutations PermK::S(K-1).

The documentation for this class was generated from the following file:

- maths/spec/perm5.h

Copyright © 1999-2016, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@maths.uq.edu.au).