Flip Reference

Array Class Reference

Inherits from

BasicType

Declared in

flip/Array.h

template <class T> class Array;

flip::Array is a sequence container, that is its elements are ordered in a strict linear sequence.

Addition, removal and moving the elements within the array or accross arrays does not invalidate the iterators or references.

The Array itself provides support for modification introspection. When modifying the content of the Array, the previous representation of the array 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 elements need to be explicitly ordered.

When elements order can be deduced from their properties (that is an comparing to elements is possible), Collection shall be prefered.

When elements do not have a particular order, then Collection shall be prefered.

Finally when a container needs to have an important number of elements and should be accessed with maximum speed, Vector could be prefered, acknowledging that the latter does not provide very good concurrency and its element are not flip objects.

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 Array

Destructor

Destructs the Array

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 array_iterator to the beginning

gend gcend

Returns a generic array_iterator to the end

Modifiers

clear

Clears the contents

insert

Inserts elements

emplace

Constructs element in-place

erase

Erases elements

splice

Moves elements

Member Functions

Constructor

Array ();                     (1)
Array (const Array & other);  (2)
  1. Default constructor, constructs an empty container.
  2. Copy constructor. Constructs the container with copy of elements of other.

Destructor

~Array ();

Destructor.


operator =

Array & operator = (const Array & other); (1)

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 Array::iterator for more details.


end cend

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

Returns an iterator to the end.

See Array::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 Array::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 Array::iterator for more details.


gbegin gcbegin

array_iterator       gbegin ();
const_array_iterator gbegin () const;
const_array_iterator gcbegin () const;

Returns a generic array_iterator to the beginning.

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

See array_iterator for more details.


gend gcend

array_iterator       gend ();
const_array_iterator gend () const;
const_array_iterator gcend () const;

Returns a generic array_iterator to the end.

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

See array_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 (iterator pos, const value_type & value);            (1)
template <class U>
iterator insert (iterator pos, const U & value);                     (2)
template <class U>
iterator insert (iterator pos, std::unique_ptr <U> && value);        (3)
template <class InputIterator>
void insert (iterator pos, InputIterator it, InputIterator it_end);  (4)
  1. Inserts a copy of value in the container before position pos.
  2. Inserts a copy of value of type U in the container before position pos.
  3. Inserts by moving the content of value in the container before position pos.
  4. Inserts a copy of the elements from range [it, it_end) before position pos.

emplace

template <class... Args>
iterator emplace (iterator pos, Args &&... args);     (1)
template <class U, class... Args>
iterator emplace (iterator pos, Args &&... args);     (2)
iterator emplace (iterator pos, const Mold & mold);   (3)
template <class U>
iterator emplace (iterator pos, const Mold & mold);   (4)
  1. Emplaces a new element constructed in-place with arguments args before position pos.
  2. Emplaces a new element of type U constructed in-place with arguments args before position pos.
  3. Emplaces a new element casted from mold before position pos.
  4. Emplaces a new element of type U casted from mold before position pos.

erase

iterator erase (iterator it);                (1)
void  erase (iterator it, iterator it_end);  (2)
  1. Erases element at position it. Returns the iterator following it.
  2. Erases elements in the range [it, it_end).

splice

iterator splice (iterator pos, Array & other, iterator it);

Moves element at position it from other to *this before position pos. Returns an iterator to that element.

Note: other and *this might refer to the same object, allowing an object to move inside the container.

To detect move in a container, see Array::iterator for mode details.