Map Class Reference

Inherits from	`BasicType`
Declared in	`flip/Map.h`

template <class T> class Map;

flip::Map is a key/value container.

The key is implicitly a type that can be serialized. Supported keys are either character strings or numbers.

Addition or removal of the elements in the map does not invalidate the iterators or references.

The Map itself provides support for modification introspection. When modifying the content of the Map, the previous representation of the map is still present, and can be accessed for every elements using the methods added, resident or removed.

WARNING: Unlike the C++ standard library, when an element is erased from a container, and if iterating over the container before commit, the element is still present until the modification is commited, but the element is marked as removed.

This container is used when the set of keys is theorically known in advance so that Flip does not need to use chaotic behaviors to allow concurrency.

It can be seen as a way to support dynamic members or properties of a Flip class, where the member's identifiers or names can only be known at runtime.

Unlike Collection or Array, Map element types cannot be polymorphic.

Template Parameters

`T`	The type of the elements. `T` must inherit from `flip::Object`

Member Types

`value_type`	`T`
`reference`	`T &`
`const_reference`	`const T &`
`pointer`	`T *`
`const_pointer`	`const T *`
`iterator`	Bidirectional access iterator
`const_iterator`	Constant bidirectional access iterator
`reverse_iterator`	Bidirectional access iterator
`const_reverse_iterator`	Constant bidirectional access iterator
`difference_type`	`std::ptrdiff_t`
`size_type`	`std::size_t`

Member Functions Synopsys

Constructor	Constructs the `Map`
Destructor	Destructs the `Map`
`operator =`	Assigns values to the container

Document Management

`document`	Returns the document to which the object is attached to
`ref`	Returns the unique reference number of the object
`added`	Returns `true` iff the object was just attached to the document tree
`removed`	Returns `true` iff the object was just detached from the document tree
`resident`	Returns `true` iff the object was neither attached nor detached from the document tree
`changed`	Returns `true` iff the object or one of its children was modified
`ancestor`	Returns a reference to a parent in the current parent chain of the object
`disable_in_undo`	Disables the record state modification in history
`inherit_in_undo`	Inherits the record state modification in history
`is_in_undo_enabled`	Returns `true` iff this object modifications are recorded in history
`revert`	Reverts all the changes made to the object and its children if any
`assign`	Replaces the content of the object with the content of the provided object

Iterators

`begin cbegin`	Returns an iterator to the beginning
`end cend`	Returns an iterator to the end
`rbegin crbegin`	Returns a reverse iterator to the beginning
`rend crend`	Returns a reverse iterator to the end
`gbegin gcbegin`	Returns a generic `map_iterator` to the beginning
`gend gcend`	Returns a generic `map_iterator` to the end

Modifiers

`clear`	Clears the contents
`insert`	Inserts elements
`emplace`	Constructs element in-place
`erase`	Erases elements

Member Functions

Constructor

Map ();                     (1)
Map (const Map & other);    (2)

Default constructor, constructs an empty container.
Copy constructor. Constructs the container with copy of elements of other.

Destructor

~Map ();

Destructor.

`operator =`

Map & operator = (const Map & other);

Copy assignment operator.

`document`

DocumentBase & document () const;

Returns the document to which the object is attached to.

WARNING: Temporary flip objects are not attached to a document

`ref`

const Ref & ref () const;

Returns the unique reference number of the object.

`added`

bool  added () const;

Returns true iff the object was just attached to the document tree.

Example :

void  Observer::document_changed (Note & note)
{
   if (note.added ())
   {
      // A note was added to the document. Create the corresponding
      // view element
      note.entity ().emplace <NoteView> ();
   }
   [...]
}

`removed`

bool  removed () const;

Returns true iff the object was just detached from the document tree.

Example :

void  Observer::document_changed (Note & note)
{
   [...]
   if (note.removed ())
   {
      // A note was removed from the document. Release the corresponding
      // view element
      note.entity ().erase <NoteView> ();
   }
}

`resident`

bool  resident () const;

Returns true iff the object was neither attached nor detached from the document tree.

An object can be resident but moved. In this case the iterator pointing to it will allow to detect the move.

Example :

void  Observer::document_changed (Array <Track> & tracks)
{
   auto it = tracks.begin ();
   auto it_end = tracks.end ();
   for (; it != it_end ; ++it)
   {
      Track & track = *it;
      if (it.added () && track.resident ())
      {
         // the track was moved in the container
         // this is the destination position
      }
      if (it.added () && track.resident ())
      {
         // the track was moved in the container
         // this is the source position
      }
   }
}

`changed`

bool  changed () const;

Returns true iff the object or one of its children was modified.

Example :

void  Observer::document_changed (Note & note)
{
   auto & view = note.entity ().use <ViewNote> ();
   if (note.changed ())
   {
      // one or more properties of the note changed
      if (note.position.changed ())
      {
         view.set_position (note.position);
      }
      if (note.duration.changed ())
      {
         view.set_duration (note.duration);
      }
   }
}

`ancestor`

template <class T>   T &   ancestor ();
template <class T>   const T &   ancestor () const;

Returns a reference to a parent in the current parent chain of the object.

Note: If an object or its parent is moved from one container to another, this function will always return the current parent, that is not the previous one

`disable_in_undo`

void   disable_in_undo ();

Disables the record state modification in history of the object and its subtree if any.

Example :

void  add_user (Root & root)
{
   // emplace a new User of the document to store
   // user specific data. User is constructed with
   // the unique user id number given at document
   // creation
   User & user = root.users.emplace <User> (root.document ().user ());
   // we don't want the scroll position in the document
   // to be part of undo
   user.scroll_position.disable_in_undo ();
}

`inherit_in_undo`

void   inherit_in_undo ();

Inherits the record state modification in history of the object and its subtree if any, from its parent state. This is the default mode.

Note: If the Root object of the tree is in inherited mode, then it is considered as enabled in undo.

`is_in_undo_enabled`

bool  is_in_undo_enabled () const;

Returns true iff this object modifications are recorded in history. The function recursively search for disabled state starting from the object itself and navigating through the parent objects, if the state is inherited.

`revert`

void  revert () const;

Reverts all the changes make to the object and its children if any.

Example :

// initially, note.position == 1
note.position = 2;
note.revert ();
// now, note.position == 1

`assign`

void  assign (const Type & rhs);

Replaces the content of the object with the content of the provided object. Both objects need to be bound to a document for the function to succeed.

Example :

// initially :
// note.position == 1
// note.duration == 3
// note2.position == 2
// note2.duration == 1
note.assign (note2);
// now :
// note.position == 2
// note.duration == 1

`begin cbegin`

iterator       begin ();
const_iterator begin () const;
const_iterator cbegin () const;

Returns an iterator to the beginning.

See Map::iterator for more details.

`end cend`

iterator       end ();
const_iterator end () const;
const_iterator cend () const;

Returns an iterator to the end.

See Map::iterator for more details.

`rbegin crbegin`

reverse_iterator       rbegin ();
const_reverse_iterator rbegin () const;
const_reverse_iterator crbegin () const;

Returns a reverse iterator to the beginning.

See Map::iterator for more details.

`rend crend`

reverse_iterator       rend ();
const_reverse_iterator rend () const;
const_reverse_iterator crend () const;

Returns a reverse iterator to the end.

See Map::iterator for more details.

`gbegin gcbegin`

map_iterator       gbegin ();
const_map_iterator gbegin () const;
const_map_iterator gcbegin () const;

Returns a generic map_iterator to the beginning.

Generic iterators are used to iterate over any template class Map instance, whatever the specialization of the template class.

See map_iterator for more details.

`gend gcend`

map_iterator       gbegin ();
const_map_iterator gbegin () const;
const_map_iterator gcbegin () const;

Returns a generic map_iterator to the end.

Generic iterators are used to iterate over any template class Map instance, whatever the specialization of the template class.

See map_iterator for more details.

`clear`

void  clear ();

Removes all the elements from the container.

This is equivalent to calling erase on every non-removed element of the container.

`insert`

iterator insert (const value_type & value);            (1)
template <class InputIterator>
void insert (InputIterator it, InputIterator it_end);  (2)

Inserts a copy of value in the container.
Inserts a copy of the elements from range [it, it_end).

`emplace`

template <class... Args>
iterator emplace (Args &&... args);     (1)
iterator emplace (const Mold & mold);   (2)

Emplaces a new element constructed in-place with arguments args.
Emplaces a new element casted from mold.

`erase`

iterator erase (iterator it);

Erases element at position it. Returns the iterator following it.

previous next