MapApi::Translate( const StrPtr &, StrBuf&, MapDir )

Translates a file path from one side of a mapping to the other.

Virtual?	No
Class	MapApi
Arguments	const StrPtr & from	the input path
	StrBuf & to	the output path
	MapDir d	the direction in which to translate (by default, MapLeftRight)
Returns	bool	whether or not the translation succeeded

Notes

The Translate() function is used to determine the effect of the mapping on any particular file. In the case of a two-sided mapping (such as a client view), it indicates where any given depot file maps in the client, or vice versa. In the case of a one-sided mapping (such as a protection table), it simply indicates whether a particular file is mapped at all.

If the specified MapDir is MapLeftRight, the input path is translated from the left side of the mapping to the right side of the mapping. If the MapDir is MapRightLeft, the mapping is effectively inverted, so that the input path is translated from the right side to the left.

If the input path does not match anything in the left side of the mapping (or the right side in the MapRightLeft case), the translation fails just as if the input path had been excluded from the mapping.

Translate() is designed to map single files. To model the effect of passing a broader path through a mapping, create a new one-sided mapping that represents that path and Join() it with the other mapping.

Examples

See the examples for Insert() and Join().