001/**
002 *
003 * Copyright (c) 2014, the Railo Company Ltd. All rights reserved.
004 *
005 * This library is free software; you can redistribute it and/or
006 * modify it under the terms of the GNU Lesser General Public
007 * License as published by the Free Software Foundation; either 
008 * version 2.1 of the License, or (at your option) any later version.
009 * 
010 * This library is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
013 * Lesser General Public License for more details.
014 * 
015 * You should have received a copy of the GNU Lesser General Public 
016 * License along with this library.  If not, see <http://www.gnu.org/licenses/>.
017 * 
018 **/
019package lucee.runtime.type;
020import java.util.Comparator;
021import java.util.List;
022
023import lucee.runtime.exp.PageException;
024
025/**
026 * 
027 */
028public interface Array extends Collection,Cloneable,Objects {
029                
030        /**
031         * return dimension of the array
032         * @return dimension of the array
033         */
034        public int getDimension();
035        
036        /**
037         * return object a given position, key can only be a integer from 1 to array len
038         * @param key key as integer
039         * @return value at key position
040         */
041        public Object get(int key, Object defaultValue);
042        
043        /**
044         * return object a given position, key can only be a integer from 1 to array len
045         * @param key key as integer
046         * @return value at key position
047         * @throws PageException
048         */
049        public Object getE(int key) throws PageException;
050        
051        /**
052         * set value at defined position, on error return null
053         * @param key key of the new value
054         * @param value value to set
055         * @return setted value
056         */
057        public Object setEL(int key, Object value);
058        
059        /**
060         * set value at defined position
061         * @param key 
062         * @param value
063         * @return defined value
064         * @throws PageException
065         */
066        public Object setE(int key, Object value) throws PageException;
067        
068        /**
069         * @return return all array keys as int
070         */
071        public int[] intKeys();
072        
073        /**
074         * insert a value add defined position 
075         * @param key position to insert
076         * @param value value to insert
077         * @return has done or not
078         * @throws PageException
079         */
080        public boolean insert(int key, Object value) throws PageException;
081        
082        /**
083         * append a new value to the end of the array
084         * @param o value to insert
085         * @return inserted value
086         * @throws PageException
087         */
088        public Object append(Object o) throws PageException;
089        
090        public Object appendEL(Object o);
091        
092        /**
093         * add a new value to the begin of the array
094         * @param o value to insert
095         * @return inserted value
096         * @throws PageException
097         */
098        public Object prepend(Object o) throws PageException;
099        
100        /**
101         * resize array to defined size
102         * @param to new minimum size of the array
103         * @throws PageException
104         */
105        public void resize(int to) throws PageException;
106
107        /**
108         * sort values of a array
109         * @param sortType search type (text,textnocase,numeric)
110         * @param sortOrder (asc,desc)
111         * @throws PageException
112         * @deprecated use instead <code>sort(Comparator comp)</code>
113         */
114        public void sort(String sortType, String sortOrder) throws PageException;
115        
116        
117        public void sort(Comparator comp);
118        
119        /**
120         * @return return arra as native (Java) Object Array
121         */
122        public Object[] toArray();
123        
124        /**
125         * @return return array as ArrayList
126         */
127        //public ArrayList toArrayList();
128        
129        public List toList();
130
131        
132        /**
133         * removes a value ad defined key
134         * @param key key to remove
135         * @return retuns if value is removed or not
136         * @throws PageException
137        */
138        public Object removeE(int key) throws PageException;    
139        
140        /**
141         * removes a value ad defined key
142         * @param key key to remove
143         * @return retuns if value is removed or not
144        */
145        public Object removeEL(int key) ;
146    
147    /**
148     * contains this key
149     * @param key
150     * @return returns if collection has a key with given name
151     */
152    public boolean containsKey(int key);
153}