Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

P4 API for Go Documentation | 2025.2

# P4Map struct

## Description

The `P4Map` struct provides a utility for managing and manipulating mappings in a P4 Server. These mappings are commonly used for depot-to-client views, branch mappings, or stream views. The `P4Map` struct allows for operations such as adding mappings, reversing mappings, translating paths, and iterating over the mappings. It provides a structured and programmatic way to handle complex mapping scenarios.

## Table of methods

Use the P4Map struct to create and work with Perforce mappings without connecting to the server.

Method | Description
--- | ---
`NewMap()` | Creates and initializes a new `P4Map` instance.
`Close()` | Cleans up and releases resources associated with the `P4Map` instance.
`JoinMap(map1, map2)` | Joins two maps to create a third map.
`Clear()` | Empties a map.
`Count() int` | Returns the number of entries in a map.
`Insert(lhs string, rhs string, flag P4MapType)` | Inserts an entry into the map.
`IsEmpty() bool` | Tests whether or not the map object is empty.
`Translate(input string, dir P4MapDirection) string` | Translate a string through a map.
`TranslateArray(input string, dir P4MapDirection) []string` | Translate a array through a map.
`Reverse()` | Returns a new mapping with the left and right sides reversed.
`Lhs(i int) string` | Returns the left side as an array.
`Rhs(i int) string` | Returns the right side as an array.
`Type(i int) P4MapType` | Retrieves the type of the mapping at the specified index.
`Array()` | Returns the map as an array.
`String()` | Returns the map as a string.

## Methods

### `NewMap() -> *P4Map`

Creates and returns a new `P4Map` instance. This initializes an empty mapping.

### `map.Insert(lhs string, rhs string, flag P4MapType)`

Adds a new mapping to the `P4Map`.

- `lhs`: The left-hand side of the mapping.

- `rhs`: The right-hand side of the mapping.

- `flag`: The type of mapping (for example, `include`, `exclude`, `overlay`).

### `map.Clear()`

Clears all mappings from the `P4Map`.

### `map.Count() -> int`

Returns the number of mappings in the `P4Map`.

### `map.Reverse()`

Reverses the mappings in the `P4Map`, swapping the left-hand side (LHS) and right-hand side (RHS) of each mapping.

### `map.Translate(input string, dir P4MapDirection) -> string`

Translates a single path using the mappings in the specified direction.

- `input`: The path to translate.

- `dir`: The direction of translation (`P4MAP_LEFT_RIGHT` or `P4MAP_RIGHT_LEFT`).

### `map.TranslateArray(input string, dir P4MapDirection) -> []string`

Translates a single path into an array of possible results using the mappings in the specified direction.

- `input`: The path to translate.

- `dir`: The direction of translation (`P4MAP_LEFT_RIGHT` or `P4MAP_RIGHT_LEFT`).

### `map.Lhs(i int) -> string`

Returns the left-hand side of the mapping at the specified index.

### `map.Rhs(i int) -> string`

Returns the right-hand side of the mapping at the specified index.

### `map.Type(i int) -> P4MapType`

Returns the type of mapping (for example, `include`, `exclude`, `overlay`) at the specified index.

### `map.Array() -> []string`

Returns all mappings as an array of strings, where each string represents a mapping in the format `<flag>lhs rhs`.

### `JoinMap(m1 *P4Map, m2 *P4Map) -> *P4Map`

Joins two `P4Map` instances and returns a new `P4Map` containing the combined mappings.

### `map.String() -> string`

Returns all mappings as a single string, with each mapping on a new line.

### `map.Close()`

Frees the resources associated with the `P4Map` instance.

## Example

This example demonstrates how to use the `P4Map` to manage and manipulate mappings in a Perforce environment.

Copy

    import (
        "fmt"
        "p4"
    )

    p4Map := p4.NewMap()
    defer p4Map.Close()

    // Insert mappings into the first map
    p4Map.Insert("//workspace/projectA/...", "//depot/projectA/...", P4MAP_INCLUDE)
    p4Map.Insert("//workspace/projectA/dir1/...", "//depot/projectA/dir1/...", P4MAP_EXCLUDE)
    p4Map.Insert("//workspace/projectB/...", "//depot/projectB/...", P4MAP_OVERLAY)

    // Print the mappings
    for i := 0; i < p4Map.Count(); i++ {
        fmt.Printf("  %s -> %s (Type: %d)\n", p4Map.Lhs(i), p4Map.Rhs(i), p4Map.Type(i))
    }

    // Reverse the map
    p4Map.Reverse()
    fmt.Println("\nMappings in p4Map after reversing:")
    for i := 0; i < p4Map.Count(); i++ {
        fmt.Printf("  %s -> %s (Type: %d)\n", p4Map.Lhs(i), p4Map.Rhs(i), p4Map.Type(i))
    }

    // Translate a path from left to right
    inputPath := "//depot/projectA/file.txt"
    translatedPath := p4Map.Translate(inputPath, P4MAP_LEFT_RIGHT)
    fmt.Printf("\nTranslated Path (Left to Right): %s -> %s\n", inputPath, translatedPath)

    // Translate a path from right to left
    inputPath = "//workspace/projectA/file.txt"
    translatedPath = p4Map.Translate(inputPath, P4MAP_RIGHT_LEFT)
    fmt.Printf("Translated Path (Right to Left): %s -> %s\n", inputPath, translatedPath)

    // Create a second map
    wsMap := p4.NewMap()
    defer wsMap.Close()

    // Insert mappings into the second map
    wsMap.Insert("//workspace/...", "/home/user/workspace/...", P4MAP_INCLUDE)

    // Join the two maps
    joinedMap := p4.JoinMap(p4Map, wsMap)
    defer joinedMap.Close()

    // Print the mappings in the joined map
    fmt.Println("\nMappings in joinedMap:")
    for i := 0; i < joinedMap.Count(); i++ {
        fmt.Printf("  %s -> %s (Type: %d)\n", joinedMap.Lhs(i), joinedMap.Rhs(i), joinedMap.Type(i))
    }

    // Translate a depot path to a local path using the joined map
    depotPath := "//depot/projectA/file.txt"
    localPath := joinedMap.Translate(depotPath, P4MAP_LEFT_RIGHT)
    fmt.Printf("\nTranslated Path (Depot to Local): %s -> %s\n", depotPath, localPath)

    // Translate a local path back to a depot path
    reversedPath := joinedMap.Translate("/home/user/workspace/projectA/file.txt", P4MAP_RIGHT_LEFT)
    fmt.Printf("Translated Path (Local to Depot): /home/user/workspace/projectA/file.txt -> %s\n", reversedPath)

### Output:

Copy

    //workspace/projectA/... -> //depot/projectA/... (Type: 0)
    //workspace/projectA/dir1/... -> //depot/projectA/dir1/... (Type: 1)
    //workspace/projectB/... -> //depot/projectB/... (Type: 2)

    Mappings in p4Map after reversing:
    //depot/projectA/... -> //workspace/projectA/... (Type: 0)
    //depot/projectA/dir1/... -> //workspace/projectA/dir1/... (Type: 1)
    //depot/projectB/... -> //workspace/projectB/... (Type: 2)

    Translated Path (Left to Right): //depot/projectA/file.txt -> //workspace/projectA/file.txt
    Translated Path (Right to Left): //workspace/projectA/file.txt -> //depot/projectA/file.txt

    Mappings in joinedMap:
    //depot/projectA/... -> /home/user/workspace/projectA/... (Type: 0)
    //depot/projectA/dir1/... -> /home/user/workspace/projectA/dir1/... (Type: 1)
    //depot/projectB/... -> /home/user/workspace/projectB/... (Type: 2)

    Translated Path (Depot to Local):
    //depot/projectA/file.txt -> /home/user/workspace/projectA/file.txt

    Translated Path (Local to Depot):
    /home/user/workspace/projectA/file.txt -> //depot/projectA/file.txt

Your search for returned results