<commit_before>////////////////////////////////////////////////////////////////////////////////
//
//  ADOBE SYSTEMS INCORPORATED
//  Copyright 2005-2010 Adobe Systems Incorporated
//  All Rights Reserved.
//
//  NOTICE: Adobe permits you to use, modify, and distribute this file
//  in accordance with the terms of the license agreement accompanying it.
//
////////////////////////////////////////////////////////////////////////////////

package mx.collections
{

    /**
     *  The <code>ISort</code> interface defines the interface for classes that
     *  provide the sorting information required to sort the
     *  data of a collection view.
     * 
     *  @see mx.collections.ICollectionView
     *  @see mx.collections.ISortField
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 4.5
     */
public interface ISort
{
    //--------------------------------------------------------------------------
    //
    //  Properties
    //
    //--------------------------------------------------------------------------

    /**
     *  The method used to compare items when sorting.
     *  If you specify this property, Flex ignores any 
     *  <code>compareFunction</code> properties that you specify in the 
     *  ISortField objects that you use in this class.
     *
     *  <p>The compare function must have the following signature:</p>
     *
     *  <pre><code>
     *
     *     function [name](a:Object, b:Object, fields:Array = null):int
     *
     *  </code></pre>
     *
     *  <p>This function must return the following
     *  <ul>
     *        <li>-1, if <code>a</code> should appear before <code>b</code> in
     *        the sorted sequence</li>
     *        <li>0, if <code>a</code> equals <code>b</code></li>
     *        <li>1, if <code>a</code> should appear after <code>b</code> in the
     *        sorted sequence</li>
     *  </ul></p>
     *  <p>To return to the internal comparision function set this value to
     *  <code>null</code>.</p>
     *  <p>
     *  The <code>fields</code> array specifies the object fields
     *  to compare.
     *  Typically the algorithm will compare properties until the field list is
     *  exhausted or a non zero value can be returned.
     *  For example:</p>
     *
     *  <pre><code>
     *    function myCompare(a:Object, b:Object, fields:Array = null):int
     *    {
     *        var result:int = 0;
     *        var i:int = 0;
     *        var propList:Array = fields ? fields : internalPropList;
     *        var len:int = propList.length;
     *        var propName:String;
     *        while (result == 0 &amp;&amp; (i &lt; len))
     *        {
     *            propName = propList[i];
     *            result = compareValues(a[propName], b[propName]);
     *            i++;
     *        }
     *        return result;
     *    }
     *
     *    function compareValues(a:Object, b:Object):int
     *    {
     *        if (a == null &amp;&amp; b == null)
     *            return 0;
     *
     *        if (a == null)
     *          return 1;
     *
     *        if (b == null)
     *           return -1;
     *
     *        if (a &lt; b)
     *            return -1;
     *
     *        if (a &gt; b)
     *            return 1;
     *
     *        return 0;
     *    }
     *  </code></pre>
     *
     *  <p>The default value is an internal compare function that can perform
     *  a string, numeric, or date comparison in ascending or descending order.
     *  Specify your own function only if you need a need a custom
     *  comparison algorithm. This is normally only the case if a calculated
     *  field is used in a display.</p>
     *
     *  <p>Alternatively you can specify separate compare functions for each
     *  sort field by using the ISortField class <code>compareFunction</code>
     *  property; This way you can use the default comparison for some
     *  fields and a custom comparison for others.</p>
     *
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 4.5
     */
    function get compareFunction():Function;
    function set compareFunction(value:Function):void;

    /**
     *  An Array of ISortField objects that specifies the fields to compare.
     *  The order of the ISortField objects in the array determines
     *  field priority order when sorting.
     *  The default sort comparator checks the sort fields in array
     *  order until it determinines a sort order for the two
     *  fields being compared.
     *
     *  @default null
     *
     *  @see ISortField
     *
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 4.5
     */
    function get fields():Array;
    function set fields(value:Array):void;

    /**
     *  Indicates if the sort should be unique.
     *  Unique sorts fail if any value or combined value specified by the
     *  fields listed in the fields property result in an indeterminate or
     *  non-unique sort order; that is, if two or more items have identical
     *  sort field values. An error is thrown if the sort is not unique.
     *
     *  @default false
     *
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 4.5
     */
    function get unique():Boolean;
    function set unique(value:Boolean):void;

    //--------------------------------------------------------------------------
    //
    //  Methods
    //
    //--------------------------------------------------------------------------

    /**
     *  Finds the specified object within the specified array (or the insertion
     *  point if asked for), returning the index if found or -1 if not.
     *  The ListCollectionView class <code>find<i>xxx</i>()</code> methods use
     *  this method to find the requested item; as a general rule, it is
     *  easier to use these functions, and not <code>findItem()</code> to find
     *  data in ListCollectionView-based objects.
     *  You call the <code>findItem()</code> method directly when writing a
     *  class that supports sorting, such as a new ICollectionView
     *  implementation.
     *
     *  @param items the Array within which to search.
     *  @param values Object containing the properties to look for (or
     *                the object to search for, itself).
     *                The object must consist of field name/value pairs, where
     *                the field names are names of fields specified by the
     *                <code>fields</code> property, in the same order they
     *                are used in that property.
     *                You do not have to specify all of the fields from the
     *                <code>fields</code> property, but you
     *                cannot skip any in the order.
     *                Therefore, if the <code>fields</code>
     *                properity lists three fields, you can specify its first
     *                and second fields in this parameter, but you cannot<commit_msg>Transferred from the Adobe Open Source Subversion Repository<commit_after>////////////////////////////////////////////////////////////////////////////////
//
//  ADOBE SYSTEMS INCORPORATED
//  Copyright 2005-2010 Adobe Systems Incorporated
//  All Rights Reserved.
//
//  NOTICE: Adobe permits you to use, modify, and distribute this file
//  in accordance with the terms of the license agreement accompanying it.
//
////////////////////////////////////////////////////////////////////////////////

package mx.collections
{

    /**
     *  The <code>ISort</code> interface defines the interface for classes that
     *  provide the sorting information required to sort the
     *  data of a collection view.
     * 
     *  @see mx.collections.ICollectionView
     *  @see mx.collections.ISortField
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 4.5
     */
public interface ISort
{
    //--------------------------------------------------------------------------
    //
    //  Properties
    //
    //--------------------------------------------------------------------------

    /**
     *  The method used to compare items when sorting.
     *  If you specify this property, Flex ignores any 
     *  <code>compareFunction</code> properties that you specify in the 
     *  ISortField objects that you use in this class.
     *
     *  <p>The compare function must have the following signature:</p>
     *
     *  <pre><code>
     *
     *     function [name](a:Object, b:Object, fields:Array = null):int
     *
     *  </code></pre>
     *
     *  <p>This function must return the following
     *  <ul>
     *        <li>-1, if <code>a</code> should appear before <code>b</code> in
     *        the sorted sequence</li>
     *        <li>0, if <code>a</code> equals <code>b</code></li>
     *        <li>1, if <code>a</code> should appear after <code>b</code> in the
     *        sorted sequence</li>
     *  </ul></p>
     *  <p>To return to the internal comparision function set this value to
     *  <code>null</code>.</p>
     *  <p>
     *  The <code>fields</code> array specifies the object fields
     *  to compare.
     *  Typically the algorithm will compare properties until the field list is
     *  exhausted or a non zero value can be returned.
     *  For example:</p>
     *
     *  <pre><code>
     *    function myCompare(a:Object, b:Object, fields:Array = null):int
     *    {
     *        var result:int = 0;
     *        var i:int = 0;
     *        var propList:Array = fields ? fields : internalPropList;
     *        var len:int = propList.length;
     *        var propName:String;
     *        while (result == 0 &amp;&amp; (i &lt; len))
     *        {
     *            propName = propList[i];
     *            result = compareValues(a[propName], b[propName]);
     *            i++;
     *        }
     *        return result;
     *    }
     *
     *    function compareValues(a:Object, b:Object):int
     *    {
     *        if (a == null &amp;&amp; b == null)
     *            return 0;
     *
     *        if (a == null)
     *          return 1;
     *
     *        if (b == null)
     *           return -1;
     *
     *        if (a &lt; b)
     *            return -1;
     *
     *        if (a &gt; b)
     *            return 1;
     *
     *        return 0;
     *    }
     *  </code></pre>
     *
     *  <p>The default value is an internal compare function that can perform
     *  a string, numeric, or date comparison in ascending or descending order.
     *  Specify your own function only if you need a need a custom
     *  comparison algorithm. This is normally only the case if a calculated
     *  field is used in a display.</p>
     *
     *  <p>Alternatively you can specify separate compare functions for each
     *  sort field by using the ISortField class <code>compareFunction</code>
     *  property; This way you can use the default comparison for some
     *  fields and a custom comparison for others.</p>
     *
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 4.5
     */
    function get compareFunction():Function;
    function set compareFunction(value:Function):void;

    /**
     *  An Array of ISortField objects that specifies the fields to compare.
     *  The order of the ISortField objects in the array determines
     *  field priority order when sorting.
     *  The default sort comparator checks the sort fields in array
     *  order until it determinines a sort order for the two
     *  fields being compared.
     *
     *  @default null
     *
     *  @see ISortField
     *
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 4.5
     */
    function get fields():Array;
    function set fields(value:Array):void;

    /**
     *  Indicates if the sort should be unique.
     *  Unique sorts fail if any value or combined value specified by the
     *  fields listed in the fields property result in an indeterminate or
     *  non-unique sort order; that is, if two or more items have identical
     *  sort field values. An error is thrown if the sort is not unique.
     *
     *  @default false
     *
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 4.5
     */
    function get unique():Boolean;

    //--------------------------------------------------------------------------
    //
    //  Methods
    //
    //--------------------------------------------------------------------------

    /**
     *  Finds the specified object within the specified array (or the insertion
     *  point if asked for), returning the index if found or -1 if not.
     *  The ListCollectionView class <code>find<i>xxx</i>()</code> methods use
     *  this method to find the requested item; as a general rule, it is
     *  easier to use these functions, and not <code>findItem()</code> to find
     *  data in ListCollectionView-based objects.
     *  You call the <code>findItem()</code> method directly when writing a
     *  class that supports sorting, such as a new ICollectionView
     *  implementation.
     *
     *  @param items the Array within which to search.
     *  @param values Object containing the properties to look for (or
     *                the object to search for, itself).
     *                The object must consist of field name/value pairs, where
     *                the field names are names of fields specified by the
     *                <code>fields</code> property, in the same order they
     *                are used in that property.
     *                You do not have to specify all of the fields from the
     *                <code>fields</code> property, but you
     *                cannot skip any in the order.
     *                Therefore, if the <code>fields</code>
     *                properity lists three fields, you can specify its first
     *                and second fields in this parameter, but you cannot
{'fraction_non_alphanumeric': 0.1491338362671137, 'fraction_numerical': 0.006845487566359318, 'mean_word_length': 1.5506859077142348, 'pattern_counts': {'":': 0, '<': 131, '<?xml version=': 0, '>': 131, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3399102', 'n_tokens_mistral': 3940, 'n_tokens_neox': 3780, 'n_words': 1402}