# perldoc > User::Identity::Collection::Locations

---
type: CommandReference
command: User::Identity::Collection::Locations
mode: perldoc
section: ""
source: perldoc
---

## Quick Reference

- `User::Identity::Collection::Locations->new($name, %options)` — create a new locations collection
- `$obj->addCollection($object | <$type, %options>)` — add a location object or create and add one
- `$obj->find($name | CODE | undef)` — find a location by name or custom search
- `$obj->addRole($role | <$name, %options> | ARRAY)` — assign a role to the collection
- `$obj->removeRole($role | $name)` — remove a role from the collection

## Name

A collection of `User::Identity::Location` objects.

## Synopsis

perl
use User::Identity::Collection::Locations;
my $locations = User::Identity::Collection::Locations->new('my_locations');
## Options

Options for `new()`:

- `description` — STRING, default undef
- `item_type` — CLASS, default `User::Identity::Location`
- `name` — STRING, default 'locations'
- `parent` — OBJECT, default undef
- `roles` — ROLE or ARRAY, default undef

## Methods

### Constructors

- `User::Identity::Collection::Locations->new([$name], %options)` — create a new collection (options above)

### Attributes (inherited)

- `$obj->description()` — inherited from `User::Identity::Item`
- `$obj->itemType()` — inherited from `User::Identity::Collection`
- `$obj->name([$newname])` — inherited from `User::Identity::Item`
- `$obj->roles()` — inherited from `User::Identity::Collection`

### Collections (inherited)

- `$obj->add($collection, $role)` — inherited from `User::Identity::Item`
- `$obj->addCollection($object | <$type, %options>)` — inherited from `User::Identity::Item`
- `$obj->collection($name)` — inherited from `User::Identity::Item`
- `$obj->parent([$parent])` — inherited from `User::Identity::Item`
- `$obj->removeCollection($object | $name)` — inherited from `User::Identity::Item`
- `$obj->type()` — inherited from `User::Identity::Item`; also class method
- `$obj->user()` — inherited from `User::Identity::Item`

### Maintaining roles (inherited)

- `$obj->addRole($role | <$name, %options> | ARRAY)` — inherited from `User::Identity::Collection`
- `$obj->removeRole($role | $name)` — inherited from `User::Identity::Collection`
- `$obj->renameRole(<$role | $oldname>, $newname)` — inherited from `User::Identity::Collection`
- `$obj->sorted()` — inherited from `User::Identity::Collection`

### Searching (inherited)

- `$obj->find($name | CODE | undef)` — inherited from `User::Identity::Collection`

### Overloaded operators

- `@{}` — inherited, see `User::Identity::Collection`
- stringification — inherited, see `User::Identity::Collection`

## Diagnostics

- `$object is not a collection.` — argument is not a collection object
- `Cannot create a $type to add this to my collection.` — failed to create native type object
- `Cannot load collection module for $type ($class).` — module not found or compilation errors
- `Cannot rename $name into $newname: already exists`
- `Cannot rename $name into $newname: doesn't exist`
- `Creation of a collection via $class failed.` — class compiled but object creation failed
- `Don't know what type of collection you want to add.` — no type specified
- `No collection $name` — collection does not exist
- `Wrong type of role for $collection: requires a $expect but got a $type` — role type mismatch

## See Also

- [User::Identity::Collection](https://www.chedong.com/phpMan.php/perldoc/User%3A%3AIdentity%3A%3ACollection/markdown)
- [User::Identity::Location](https://www.chedong.com/phpMan.php/perldoc/User%3A%3AIdentity%3A%3ALocation/markdown)
- [User::Identity::Item](https://www.chedong.com/phpMan.php/perldoc/User%3A%3AIdentity%3A%3AItem/markdown)
- Part of User-Identity distribution version 1.01 (2022-02-11). Website: <http://perl.overmeer.net/CPAN/>