regina::NPerm4 Class Reference
Mathematical Support

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

`#include <maths/nperm4.h>`

## Public Types

enum | { nPerms = 24, nPerms_1 = 6 }

## Public Member Functions

| NPerm4 ()
| Creates the identity permutation. More...
| NPerm4 (int a, int b)
| Creates the transposition of a and b. More...
| NPerm4 (int a, int b, int c, int d)
| Creates a permutation mapping (0,1,2,3) to (a,b,c,d) respectively. More...
| NPerm4 (const int *image)
| Creates a permutation mapping i to image[i] for each i = 0,1,2,3. More...
| NPerm4 (int a0, int a1, int b0, int b1, int c0, int c1, int d0, int d1)
| Creates a permutation mapping (a0,b0,c0,d0) to (a1,b1,c1,d1) respectively. More...
| NPerm4 (const NPerm4 &cloneMe)
| Creates a permutation that is a clone of the given permutation. More...
unsigned char | getPermCode () const
| Returns the first-generation code representing this permutation. More...
unsigned char | getPermCode2 () const
| Returns the second-generation code representing this permutation. More...
void | setPermCode (unsigned char code)
| Sets this permutation to that represented by the given first-generation permutation code. More...
void | setPermCode2 (unsigned char code)
| Sets this permutation to that represented by the given second-generation permutation code. More...
void | setPerm (int a, int b)
| Sets this permutation to the transposition of a and b. More...
void | setPerm (int a, int b, int c, int d)
| Sets this permutation to that mapping (0,1,2,3) to (a,b,c,d) respectively. More...
NPerm4 & | operator= (const NPerm4 &cloneMe)
| Sets this permutation to be equal to the given permutation. More...
NPerm4 | operator* (const NPerm4 &q) const
| Returns the composition of this permutation with the given permutation. More...
NPerm4 | inverse () const
| Finds the inverse of this permutation. More...
int | sign () const
| Determines the sign of this permutation. More...
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 NPerm4 &other) const
| Determines if this is equal to the given permutation. More...
bool | operator!= (const NPerm4 &other) const
| Determines if this differs from the given permutation. More...
int | compareWith (const NPerm4 &other) const
| Lexicographically compares the images of (0,1,2,3) under this and the given permutation. More...
bool | isIdentity () const
| Determines if this is the identity permutation. More...
std::string | toString () const
| A deprecated alias for str(), which returns a string representation of this permutation. More...
std::string | str () const
| Returns a string representation of this permutation. 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 included. More...
int | S4Index () const
| Returns the index of this permutation in the NPerm4::S4 array. More...
int | SnIndex () const
| Returns the index of this permutation in the NPerm4::S4 array. More...
int | orderedS4Index () const
| Returns the index of this permutation in the NPerm4::orderedS4 array. More...
int | orderedSnIndex () const
| Returns the index of this permutation in the NPerm4::orderedS4 array. More...

## Static Public Member Functions

static NPerm4 | fromPermCode (unsigned char code)
| Creates a permutation from the given first-generation permutation code. More...
static NPerm4 | fromPermCode2 (unsigned char code)
| Creates a permutation from the given second-generation permutation code. More...
static bool | isPermCode (unsigned char code)
| Determines whether the given character is a valid first-generation permutation code. More...
static bool | isPermCode2 (unsigned char code)
| Determines whether the given character is a valid second-generation permutation code. More...

## Static Public Attributes

static const NPerm4 | S4 [24]
| Contains all possible permutations of four elements. More...
static const NPerm4 * | Sn
| A dimension-agnostic alias for NPerm4::S4. More...
static const unsigned | invS4 [24]
| Contains the inverses of the permutations in the array S4. More...
static const NPerm4 | orderedS4 [24]
| Contains all possible permutations of four elements in lexicographical order. More...
static const NPerm4 * | orderedSn
| A dimension-agnostic alias for NPerm4::orderedS4. More...
static const NPerm4 | S3 [6]
| Contains all possible permutations of three elements. More...
static const NPerm4 * | Sn_1
| A dimension-agnostic alias for NPerm4::S3. More...
static const unsigned | invS3 [6]
| Contains the inverses of the permutations in the array S3. More...
static const NPerm4 | orderedS3 [6]
| Contains all possible permutations of three elements in lexicographical order. More...
static const NPerm4 | S2 [2]
| Contains all possible permutations of two elements. More...
static const unsigned | invS2 [2]
| Contains the inverses of the permutations in the array S2. More...

## Friends

std::ostream & | operator<< (std::ostream &out, const NPerm4 &p)
| Writes a string representation of the given permutation to the given output stream. More...

## Detailed Description

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

Amongst other things, such permutations are used in specifying how simplices of a 3-manifold triangulation are glued together. NPerm4 objects are small enough to pass about by value instead of by reference.

Each permutation has an internal code, and this code is sufficient to reconstruct the permutation. Thus the internal code may be a useful means for passing permutation objects to and from the engine.

The internal permutation codes have changed as of Regina 4.6.1:

- First-generation codes were used internally in Regina 4.6 and earlier. These codes were characters whose lowest two bits represented the image of 0, whose next lowest two bits represented the image of 1, and so on. The routines getPermCode(), setPermCode(), fromPermCode() and isPermCode() continue to work with first-generation codes for backward compatibility. Likewise, the XML data file format continues to use first-generation codes to describe tetrahedron gluings.
- Second-generation codes are used internally in Regina 4.6.1 and above. These codes are integers between 0 and 23 inclusive, representing the index of the permutation in the array NPerm4::S4. The routines getPermCode2(), setPermCode2(), fromPermCode2() and isPermCode2() work with second-generation codes.

It is highly recommended that, if you need to work with permutation codes at all, you use second-generation codes where possible. This is because the first-generation routines incur additional overhead in converting back and forth between the second-generation codes (which are used internally by NPerm4).

Test:
  Exhaustively tested in the test suite.

## Member Enumeration Documentation

anonymous enum

Enumerator

nPerms

The total number of permutations on four elements.

This is the size of the array Sn.

Python:
  Not present.

nPerms_1

The total number of permutations on three elements.

This is the size of the array Sn_1.

Python:
  Not present.

## Constructor & Destructor Documentation

regina::NPerm4::NPerm4 | ( |  | ) |

inline

Creates the identity permutation.

regina::NPerm4::NPerm4 | ( | 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}.

Parameters

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

regina::NPerm4::NPerm4 | ( | int | a,
|  | int | b,
|  | int | c,
|  | int | d
| ) |  |

inline

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

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

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.

regina::NPerm4::NPerm4 | ( | const int * | image | ) |

inline

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

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

Python:
  Not present.

Parameters

  image | the array of images.

regina::NPerm4::NPerm4 | ( | int | a0,
|  | int | a1,
|  | int | b0,
|  | int | b1,
|  | int | c0,
|  | int | c1,
|  | int | d0,
|  | int | d1
| ) |  |

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

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

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.
  a1 | the desired image of a0.
  b1 | the desired image of b0.
  c1 | the desired image of c0.
  d1 | the desired image of d0.

regina::NPerm4::NPerm4 | ( | const NPerm4 & | cloneMe | ) |

inline

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

Parameters

  cloneMe | the permutation to clone.

## Member Function Documentation

int regina::NPerm4::compareWith | ( | const NPerm4 & | other | ) | const

inline

Lexicographically compares the images of (0,1,2,3) 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.

NPerm4 regina::NPerm4::fromPermCode | ( | unsigned char | code | ) |

inline static

Creates a permutation from the given first-generation permutation code.

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

Warning
  This routine will incur additional overhead, since NPerm4 now uses second-generation codes internally. See the class notes and the routine fromPermCode2() for details.

Parameters

  code | the first-generation code for the new permutation.

Returns
  the permutation represented by the given code.

NPerm4 regina::NPerm4::fromPermCode2 | ( | unsigned char | code | ) |

inline static

Creates a permutation from the given second-generation permutation code.

Second-generation codes are fast to work with, since they are used internally by the NPerm4 class.

Precondition
  the given code is a valid second-generation permutation code; see isPermCode2() for details.

Parameters

  code | the second-generation code for the new permutation.

Returns
  the permutation represented by the given code.

unsigned char regina::NPerm4::getPermCode | ( |  | ) | const

inline

Returns the first-generation code representing this permutation.

This code is sufficient to reproduce the entire permutation.

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

Warning
  This routine will incur additional overhead, since NPerm4 now uses second-generation codes internally. See the class notes and the routine getPermCode2() for details.

Returns
  the first-generation permutation code.

unsigned char regina::NPerm4::getPermCode2 | ( |  | ) | const

inline

Returns the second-generation code representing this permutation.

This code is sufficient to reproduce the entire permutation.

The code returned will be a valid second-generation permutation code as determined by isPermCode2().

Second-generation codes are fast to work with, since they are used internally by the NPerm4 class.

Returns
  the second-generation permutation code.

NPerm4 regina::NPerm4::inverse | ( |  | ) | const

inline

Finds the inverse of this permutation.

Returns
  the inverse of this permutation.

bool regina::NPerm4::isIdentity | ( |  | ) | const

inline

Determines if this is the identity permutation.

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

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

static bool regina::NPerm4::isPermCode | ( | unsigned char | code | ) |

static

Determines whether the given character is a valid first-generation permutation code.

Valid first-generation codes can be passed to setPermCode() or fromPermCode(), and are returned by getPermCode().

Warning
  This routine will incur additional overhead, since NPerm4 now uses second-generation codes internally. See the class notes and the routine isPermCode2() for details.

Parameters

  code | the permutation code to test.

Returns
  `true` if and only if the given code is a valid first-generation permutation code.

bool regina::NPerm4::isPermCode2 | ( | unsigned char | code | ) |

inline static

Determines whether the given character is a valid second-generation permutation code.

Valid second-generation codes can be passed to setPermCode2() or fromPermCode2(), and are returned by getPermCode2().

Second-generation codes are fast to work with, since they are used internally by the NPerm4 class.

Parameters

  code | the permutation code to test.

Returns
  `true` if and only if the given code is a valid second-generation permutation code.

bool regina::NPerm4::operator!= | ( | const NPerm4 & | 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 or 3.

Parameters

  other | the permutation with which to compare this.

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

NPerm4 regina::NPerm4::operator* | ( | const NPerm4 & | 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.

NPerm4 & regina::NPerm4::operator= | ( | const NPerm4 & | 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.

bool regina::NPerm4::operator== | ( | const NPerm4 & | 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 and 3.

Parameters

  other | the permutation with which to compare this.

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

int regina::NPerm4::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 3 inclusive.

Returns
  the image of source.

int regina::NPerm4::orderedS4Index | ( |  | ) | const

inline

Returns the index of this permutation in the NPerm4::orderedS4 array.

Returns
  the index i for which this permutation is equal to NPerm4::orderedS4[i]. This will be between 0 and 23 inclusive.

int regina::NPerm4::orderedSnIndex | ( |  | ) | const

inline

Returns the index of this permutation in the NPerm4::orderedS4 array.

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

Returns
  the index i for which this permutation is equal to NPerm4::orderedS4[i]. This will be between 0 and 23 inclusive.

int regina::NPerm4::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 3 inclusive.

Returns
  the preimage of image.

int regina::NPerm4::S4Index | ( |  | ) | const

inline

Returns the index of this permutation in the NPerm4::S4 array.

Returns
  the index i for which this permutation is equal to NPerm4::S4[i]. This will be between 0 and 23 inclusive.

void regina::NPerm4::setPerm | ( | int | a,
|  | int | b
| ) |  |

inline

Sets this permutation to 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}.

Deprecated:
  This routine is largely unnecessary, since NPerm4 objects are tiny and cheap. Just use the assignment operator instead. This routine will eventually be removed entirely in a future version of Regina.

Parameters

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

void regina::NPerm4::setPerm | ( | int | a,
|  | int | b,
|  | int | c,
|  | int | d
| ) |  |

inline

Sets this permutation to that mapping (0,1,2,3) to (a,b,c,d) respectively.

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

Deprecated:
  This routine is largely unnecessary, since NPerm4 objects are tiny and cheap. Just use the assignment operator instead. This routine will eventually be removed entirely in a future version of Regina.

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.

void regina::NPerm4::setPermCode | ( | unsigned char | code | ) |

inline

Sets this permutation to that represented by the given first-generation permutation code.

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

Warning
  This routine will incur additional overhead, since NPerm4 now uses second-generation codes internally. See the class notes and the routine setPermCode2() for details.

Parameters

  code | the first-generation code that will determine the new value of this permutation.

void regina::NPerm4::setPermCode2 | ( | unsigned char | code | ) |

inline

Sets this permutation to that represented by the given second-generation permutation code.

Second-generation codes are fast to work with, since they are used internally by the NPerm4 class.

Precondition
  the given code is a valid second-generation permutation code; see isPermCode2() for details.

Parameters

  code | the second-generation code that will determine the new value of this permutation.

int regina::NPerm4::sign | ( |  | ) | const

inline

Determines the sign of this permutation.

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

int regina::NPerm4::SnIndex | ( |  | ) | const

inline

Returns the index of this permutation in the NPerm4::S4 array.

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

Returns
  the index i for which this permutation is equal to NPerm4::S4[i]. This will be between 0 and 23 inclusive.

std::string regina::NPerm4::str | ( |  | ) | const

Returns a string representation of this permutation.

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

Returns
  a string representation of this permutation.

std::string regina::NPerm4::toString | ( |  | ) | const

inline

A deprecated alias for str(), which returns a string representation of this permutation.

Deprecated:
  This routine has (at long last) been deprecated; use the simpler-to-type str() instead.

Returns
  a string representation of this permutation.

std::string regina::NPerm4::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.

std::string regina::NPerm4::trunc3 | ( |  | ) | const

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

The resulting string will therefore have length three.

Returns
  a truncated string representation of this permutation.

## Friends And Related Function Documentation

std::ostream& operator<< | ( | std::ostream & | out,
|  | const NPerm4 & | p
| ) |  |

friend

Writes a string representation of the given permutation to the given output stream.

The format will be the same as is used by NPerm4::str().

Parameters

  out | the output stream to which to write.
  p | the permutation to write.

Returns
  a reference to out.

## Member Data Documentation

const unsigned regina::NPerm4::invS2[2]

static

Contains the inverses of the permutations in the array S2.

Specifically, the inverse of permutation `S2[i]` is the permutation `S2[ invS2[i] ]`.

Deprecated:
  This array is unnecessary, since all elements of S2 are their own inverses. This array will be removed in some future version of Regina.

const unsigned regina::NPerm4::invS3[6]

static

Contains the inverses of the permutations in the array S3.

Specifically, the inverse of permutation `S3[i]` is the permutation `S3[ invS3[i] ]`.

Deprecated:
  This is identical to the array NPerm3::invS3. This unnecessary copy in NPerm4 will be removed in some future version of Regina.

const unsigned regina::NPerm4::invS4[24]

static

Contains the inverses of the permutations in the array S4.

Specifically, the inverse of permutation `S4[i]` is the permutation `S4[ invS4[i] ]`.

const NPerm4 regina::NPerm4::orderedS3[6]

static

Contains all possible permutations of three elements in lexicographical order.

In each permutation, 3 maps to 3.

const NPerm4 regina::NPerm4::orderedS4[24]

static

Contains all possible permutations of four elements in lexicographical order.

const NPerm4* regina::NPerm4::orderedSn

static

A dimension-agnostic alias for NPerm4::orderedS4.

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

const NPerm4 regina::NPerm4::S2[2]

static

Contains all possible permutations of two elements.

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

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 (NPerm4, NPerm5 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.

const NPerm4 regina::NPerm4::S3[6]

static

Contains all possible permutations of three elements.

In each permutation, 3 maps to 3.

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 (NPerm4, NPerm5 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 NPerm3::invS3.

const NPerm4 regina::NPerm4::S4[24]

static

Contains all possible permutations of four 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.

For all permutation classes (NPerm4, NPerm5 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.

const NPerm4* regina::NPerm4::Sn

static

A dimension-agnostic alias for NPerm4::S4.

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

const NPerm4* regina::NPerm4::Sn_1

static

A dimension-agnostic alias for NPerm4::S3.

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

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

- maths/nperm4.h

Copyright © 1999-2013, 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@debian.org).