rfc:sorting_enum

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

rfc:sorting_enum [2021/09/02 16:47] – created crellrfc:sorting_enum [2021/09/02 17:45] (current) – crell
Line 8: Line 8:
 ===== Introduction ===== ===== Introduction =====
  
-This RFC proposes to add a built-in Enumeration to PHP +This RFC proposes to add a built-in Enumeration to PHP to specify the possible return values of sorting/comparison functions.  This enumeration would be easier for developers to use than the existing magic constants, although support for those remains.
  
 ===== Proposal ===== ===== Proposal =====
-All the features and examples of the proposal. 
  
-To [[http://news.php.net/php.internals/66051|paraphrase Zeev Suraski]], explain hows the proposal brings substantial value to be considered +This RFC includes two changes, specifically.
-for inclusion in one of the world's most popular programming languages.+
  
-Remember that the RFC contents should be easily reusable in the PHP Documentation.+One, the following Enumeration is defined in PHP's standard library.
  
-If applicable, you may wish to use the language specification as a reference.+<code php> 
 +enum Ordering 
 +{ 
 +    case LeftGreater; 
 +    case RightGreater; 
 +    case Equal; 
 +    case Uncomparable; 
 +} 
 +</code>
  
-===== Backward Incompatible Changes ===== +Second, all sorting and comparison functions that accept a user-supplied comparison function (''usort()'', ''uksort()'', etc.) are modified to allow the developer to return either an integer (as now) or an instance of ''Ordering''.  The semantic meaning of the enum cases is equivalent to their integer versions.
-What breaks, and what is the justification for it?+
  
-===== Proposed PHP Version(s) ===== +The primary benefit of this change is usability.  It is very easy to forget which of 1 and -1 mean which sorting direction (one of the RFC authors has to look it up every single time), whereas a closed set of values naturally maps to an enumeration.  An enumeration with named options is considerably more self-documenting.
-List the proposed PHP versions that the feature will be included in.  Use relative versions such as "next PHP 8.x" or "next PHP 8.x.y".+
  
-===== RFC Impact ===== +==== Uncomparable ====
-==== To SAPIs ==== +
-Describe the impact to CLI, Development web server, embedded PHP etc.+
  
-==== To Existing Extensions ==== +PHP currently has no explicit way to indicate that two parameters are simply not logically comparable.  In practice it rarely comes up (as most developers will only try sorting values that are in facts sortable), but it is a gap in the current design.  However, the [[rfc:user_defined_operator_overloads|User Defined Operator Overloads]] RFC, should it pass, would present additional cases where incompariable objects are compared.
-Will existing extensions be affected?+
  
-==== To Opcache ==== +PHP's current implicit mechanism is to return 1 when two values are uncomparable, regardless of which comes first.  That is highly subtle and not well known, as well as logically suspect.  Providing an explicit "this is not logical" return value is, as above, more self-documenting, more obvious to use, and offers the potential for slightly improved error handling in the engine.
-It is necessary to develop RFC's with opcache in mind, since opcache is a core extension distributed with PHP.+
  
-Please explain how you have verified your RFC's compatibility with opcache.+===== Backward Incompatible Changes =====
  
-==== New Constants ==== +The global namespace symbol "Ordering" is now taken.
-Describe any new constants so they can be accurately and comprehensively explained in the PHP documentation.+
  
-==== php.ini Defaults ==== +===== Proposed PHP Version(s) =====
-If there are any php.ini settings then list: +
-  * hardcoded default values +
-  * php.ini-development values +
-  * php.ini-production values+
  
-===== Open Issues ===== +PHP 8.2
-Make sure there are no open issues when the vote starts!+
  
-===== Unaffected PHP Functionality ===== +===== RFC Impact =====
-List existing areas/features of PHP that will not be changed by the RFC.+
  
-This helps avoid any ambiguity, shows that you have thought deeply about the RFC's impact, and helps reduces mail list noise.+===== Open Issues ===== 
 + 
 +The specific case names are subject to inevitable bikeshedding.
  
 ===== Future Scope ===== ===== Future Scope =====
-This section details areas where the feature might be improved in future, but that are not currently proposed in this RFC.+ 
 +This RFC very specifically does not remove or deprecate the existing integer returns for comparison functions.  Those will continue to work exactly as now.  Whether or not they should be removed in PHP 9 or 10 is a question for another time.
  
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
-Include these so readers know where you are heading and can discuss the proposed voting options. 
  
-===== Patches and Tests ===== +This is a simple yes/no vote, requiring 2/3 to pass.
-Links to any external patches and tests go here.+
  
-If there is no patch, make it clear who will create a patch, or whether a volunteer to help with implementation is needed. +===== Patches and Tests =====
- +
-Make it clear if the patch is intended to be the final patch, or is just a prototype.+
  
-For changes affecting the core language, you should also provide a patch for the language specification.+Pending...
  
 ===== Implementation ===== ===== Implementation =====
rfc/sorting_enum.1630601240.txt.gz · Last modified: 2021/09/02 16:47 by crell

Page Tools