|  |  | Names and renaming

## Names and renaming

Data items have names (or identifiers) that are unique for each type of item: no two items of the same type may have the same name.

There are important issues concerning names: which characters can be used in them, what is their maximum length and how to rename items either to avoid clashes with existing names or to follow the constraints on acceptable characters or length. Allowed characters and length depend on the receiver brand and model: GPSMan behaviour is controlled by some user options on this.

There should be some caution in setting these options. For instance, if data files are to be shared among users with receivers of different brands, the more strict rules should be followed. In particular, using a large maximum length may result in data loss if names are truncated and then become equal to existing names.

Waypoint names obey the following rules:

- Garmin names should only have uppercase letters and digits, even if Garmin receivers may use others (see the Garmin specification...). GPSMan also accepts either lowercase letters and hyphens, or any character, depending on the options.
- Lowrance names can have uppercase letters, digits, hyphen, single quote, period, parentheses, slash and also space.
- There are no constraints on Magellan names.

When a waypoint name with characters not allowed or exceeding the maximum length is read from a file or from the receiver, the user is asked for a new name but has the choice between applying a renaming method to it or letting GPSMan automatically generate a new name for it. This can be done not only for the present name but also for any forthcoming unacceptable name in the current input operation. The replacement name can neither be in use by other waypoint in the data-base, nor be the same as a previous replacement name in the current input operation (there is no check on whether the name is listed in a route or a group). The user can also choose to cancel the renaming in which case the waypoint is ignored. This will cause an inconsistency if it belongs to a route.

A renaming method can also be applied to waypoint names from

- the waypoint sub-menu under `Data` in the map window
- the waypoint menu in the lists window
- a group window: `Use WPs->Change Name->...`

Allowed characters in route names also depend on the brand of the receiver. Although some receivers require route names to be numbers, there are others accepting letters and other characters as well.

GPSMan does not check the characters in the route name, but will refuse to output a route with a non-numeric name to a receiver or file if the receiver protocol or the file format disallow it.

When working with Garmin receivers GPSMan will, if the option on this is selected, automatically give numbers to routes with non-numeric names when putting them on the receiver, avoiding numbers already in use for routes and without affecting the data-base. There is a counter for this, initially set to 1 and that can be reset from the receiver window or the receiver menu (`Put->Route->Set counter to 1`).

A unique name is used for each item of each type. When a new item is read in and it has the name of an item of the same type in the data-base the latter is forgotten and overwritten. Exceptions to this are waypoints with the same name and different positions

1. if the renaming option was previously selected by the user.
2. when getting data from a Garmin receiver, if the waypoints were not defined by the user.

in which case automatically generated names will be used for them.

It should be noted that

1. all input operations with the exception just mentioned are destructive: new items will replace data-base items having the same name. This is the behaviour of most GPS receivers, and avoids having obsolete information in the data-base.

2. the test for the equality of waypoint positions may fail because of rounding errors, at least when the comparison implies a change of position format or a change of datum.

Renaming raises the problem of generating a new suitable name for the item. Currently, GPSMan will try to keep the first part of the old name following it by digits. If the constraints on name length and uniqueness cannot be met, the new name will be a two-letter code for the item type and a hyphen followed by a number.

When an item is renamed, its previous name is kept in the remark field.

When generating a name for a new item or for replacing names with unacceptable characters, GPSMan will use a name with a two-letter code for the item type and a hyphen followed by a number, except in the case of routes for which a number will be used.

Renaming waypoints can lead to ambiguities in what are the actual waypoints of groups. This will only happen when reading from a file in GPSMan format having groups in which there are different waypoints under the same name.

To minimise the problems with these situations, GPSMan creates a group containing the items that were renamed and those for which there may be ambiguities, after any input operation in which they occur.

Renaming methods for waypoint names can be defined and inspected by the user from the `Definitions` menu. Each method gives a sequence of operations that are applied to the original name in order to get a new name. If the resulting name is not already in use it will be given to the waypoint; otherwise GPSMan falls back to its default method of generating names.

Each renaming method has a name, a remark and a textual description of the operators to be applied in order, one per line. The list of operators is edited from a dialog that opens up by clicking on the text. This dialog shows the same text, which can be cleared (`Clear all` button) and where an operator can be selected and deleted (`Delete` button) or moved up or down (dragging with the mouse right-button). The buttons under the `Add` label correspond to operators that can be added to the list, some of them having parameters. At the end of the dialog there is an area for experimenting the current definition on a given name: clicking on the `Apply` button the resulting name is shown together with an indication on whether the name is acceptable and not in use.

The operators available are:

1. keep first character: further operations will preserve the leftmost active character changing only the characters to its right; the leftmost active character becomes the character to the right of the previous leftmost active character; when starting the leftmost active character is the first character in the original name
2. reset: forget the current result and restart with the initial name
3. change case: change all letters to lower- or to upper-case
4. cut to the specified maximum length: the current result is chopped at the right end so that it will not have more than the given lentgh
5. insert the given string immediately before the leftmost active character,;the leftmost active character becomes the first character of the inserted string
6. append: insert the given string at the end
7. delete any: delete all occurrences of any character in the given string
8. replace characters: the two given strings must have the same length, all occurrences of each character in the first string will be replaced by the character at the same position in the second string; for instance, applying this operator with strings `AB` and `zC` means that each `A` will be replaced by a `z` and each `B` by a `C`, in this order (left to right in each string), making `AMB0aXA` into `zMC0aXz`
9. apply a regular expression substitution (for users knowing what a regular expression is): this is a call to the Tcl command `regsub` with the `-all` option; for further details see the Tcl manual pages for `regsub` and `re_syntax`
10. accept if result is a new name: the renaming process is finished if the current result is acceptable; otherwise the following operators will be applied
11. generate names using a prefix followed by a number: the prefix is the current result and the number has a specified number of digits; numbers start from 1 and all possible values are tried until a new name is found; if this fails no change is made on the current result.

Examples of renaming methods are as follows:

- the following list of operators:
  1. keep first character
  2. keep first character
  3. insert `00` at the beginning
  4. maximum length is 8
  will convert `Labrusques` into `La00brusqu`, i.e., the two first characters are preserved, `00` is inserted at the beginning of the remaining string and the result of the insertion is cut down to 8 characters
- the following list of operators:
  1. change case to upper
  2. delete any `AEIOU`
  will convert all letters to upper-case and then deletes all vowels
- to make sure there are only upper-case letters and digits and the length is at most 10, the following list could be used:
  1. change case to upper
  2. apply the regular expression substitution `[^A-Z0-9]` with an empty string: this will delete all characters that are not upper-case letters or digits (note the `^` after the opening bracket)
  3. accept if new: stop if the current name is new
  4. maximum length is 7: keep only the first 7 characters
  5. append number with 3 digits until new
  this last step may fail in giving an acceptable name, but as already mentioned if the renaming method fails, GPSMan will generate a new name using its default method.

|  |  | Names and renaming